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省 、 全 


为 什么 要 与 这 本 市 





目 第 1 版 发 行 以 来 ， 笔 者 很 欣慰 得 到 了 广大 读者 的 认可 。 本 书 一 直 
致力 于 说 明 开 发 Nginx 模 块 的 必 备 知识 ， 然 而 由 于 Nginx 功 能 党 多 且 性 能 
强大 ， 以 致 必须 要 了 解 的 基本 技能 也 很 庞杂 ， 而 第 1 版 成 书 匆 忙 ， 缺 失 
本 儿 个 进 阶 的 技巧 描述 (例如 如 何 使 用 变量 、slab 共 至 内 存 等 ， 因 此 
决定 在 第 1 版 的 基础 上 进一步 完善 。 





事实 上 ， 我 们 总 能 在 nginx.conf 配 置 文件 中 看 到 各 种 带 着 $ 符 号 的 变 
量 ， 只 要 修改 带 着 变量 的 这 一 行 行 配置 ， 束 可 以 不 用 编译 、 部 普 而 使 得 
Nginx 有 具备 新 功能 ， 这 些 文 持 变 量 的 Nginx 模 块 提供 了 极为 灵活 的 功能 ， 
第 2 版 通过 新 增 的 第 15 章 详细 介绍 了 如 何在 模块 中 文 持 HTTP 变量 ， 包 括 
如 何在 代码 中 使 用 其 他 Nginx 模 块 提供 的 变量 ， 以 及 如 何 定义 新 的 变量 
供 nginx.conf 和 其 他 第 三 方 模块 使 用 等 。 第 16 半 介绍 了 slab 共 有 至 内 存 ， 这 
古 一 套 适 用 于 小 块 内 存 快速 分 配 释放 的 内 存 省 理 方式 ， 它 非常 高 效 ， 分 
配 与 释放 速度 部 是 以 纳 秒 计算 的 ， 常 用 于 多 个 worker 进 程 之 间 的 通信 ， 
这 比 第 14 章 介绍 的 原始 的 共享 内 存 通 信 方 式 要 先进 很 多 。 第 16 章 不 仅 详 
细 介 绍 了 它 的 实现 方式 ， 也 探讨 了 它 的 优 缺 点 ， 比 如 ， 如 果 模 块 间 要 共 
译 的 蛙 个 对 象 常 第 要 消耗 数 KB 的 空间 ， 这 时 就 需要 修改 它 的 实现 〈 例 














如 增 大 定义 的 slab 页 大 小 ) ， 以 避免 内 存 的 浪费 等 


Nginx 内 存 池 在 第 1 版 中 只 是 简单 带 过 ， 第 2 版 中 新 增 了 8.7 节 介绍 了 
内 存 池 的 实现 细节 ， 以 帮助 读者 用 好 最 基础 的 内 存 池 功能 


此 外 ， 很 多 读者 反馈 需要 结合 TCP 来 谈 谈 Nginx， 因 此 在 9.10 节 中 笔 
者 试图 在 不 陷入 Linux 内 核 细 节 的 情况 下 ， 简 要 介绍 了 TCP 以 清晰 了 解 
Nginx 的 事件 框架 ， 了 解 Nginx 的 高 并 发 能 力 。 


一 版 新 增 的 第 15 章 的 样 例 代 码 可 以 从 http://nginx.taohui.org.cn 站 
点 上 下 载 。 


忆 笔 者 工作 楷 忙 ， 以 致 第 2 版 拖 稿 严重 ， 读 者 的 邮件 也 无 法 及 时 回 
复 ， 非 常 抱 娄 。 从 这 版 开始 会 把 曾经 的 回复 整理 后 放 在 网 站 上 ， 想 必 这 
比 回复 邮件 要 更 有 效率 些 。 





读者 对 象 


本 书 适合 以 下 读者 阅读 。 


对 Nginx 及 如 何 将 它 搭建 成 一 个 高 性 能 的 Web 服 务 器 感 兴趣 的 读 


` 希望 通过 开发 特定 的 HTTP 模 块 实现 高 性 能 Web 服 务 器 的 读者 。 


. 希望 了 解 Nginx 的 架构 设计 ， 学 习 其 怎样 充分 使 用 服务 器 上 的 硬 
件 资 源 的 读者 。 
了解 如 何 快速 定位 、 修 复 Neinx 中 深层 次 Bug 的 读者 。 


. 希望 利用 Nginx 提 供 的 框架 ， 设 计 出 任何 基于 TCP 的 、 无 阻塞 
的 、 易 于 扩展 的 服务 器 的 读者 。 


匠 巡 知识 


如 果 仅 希望 了 解 怎样 使 用 已 有 的 Nginx 功 能 搭建 服务 器 ， 那 么 阅读 
本 书 不 需要 什么 先决 条 件 。 但 如 果 和 希望 通过 阅读 本 书 的 第 二 、 第 三 两 部 

， 来 学 习 Nginx 的 模块 开 及 和 架构 设计 技巧 时 ， 则 必须 了 解 C 语 言 的 基 
本 语法 。 在 阅读 本 书 第 三 部 分 时 ， 需 要 读者 对 TCP 有 一 个 基本 的 了 解 ， 
同时 对 Linux 操 作 系统 也 应 该 有 简单 的 了 解 。 


如 何 阅 读本 书 


我 很 希望 将 本 书写 成 一 本 “step by step” 式 〈 循 序 渐进 式 ) 的 书籍 
因为 这 样 最 能 节省 读者 的 时 间 ， 然 而 ， 由 于 3 个 主要 写作 目的 想 解决 的 
问题 都 不 是 那么 简单 ， 所 以 这 本 书 只 能 做 一 个 折 中 的 处 理 。 


在 第 一 部 分 的 前 两 章 中 ， 将 只 探讨 如 何 使 用 Nginx 这 一 个 问题 。 阅 


读 这 一 部 分 的 读者 不 需要 了 解 C 语 言 ， 就 可 以 学 习 如 何 部 署 Nginx， 学 习 
如 何 向 其 中 添加 各 种 官方 、 第 三 方 的 功能 模块 ， 如 何 通过 修改 配置 文件 
来 更 改 Nginx 及 各 模块 的 功能 ， 如 何 修改 Linux 操 作 系统 上 的 参数 来 优化 
服务 器 性 能 ， 最 终 向 用 户 提供 企业 级 的 Web 服 务 器 。 这 一 部 分 介绍 配置 


项 的 方式 ， 更 偏重 于 领 着 对 Nginx 还 比较 陌生 的 读者 熟悉 它 ， 通 过 了 解 
儿 个 基本 Nginx 模 块 的 配置 修改 方式 ， 进 而 使 读者 可 以 通过 查询 官网 、 


第 三 方 网 站 来 了 解 如 何 使 用 所 有 Nginx 模 块 的 用 法 。 





在 第 二 部 分 的 第 3 章 ~ 第 7 章 中 ， 都 是 以 例子 来 介绍 HTTP 模 块 的 开发 
方式 的 ， 这 里 有 些 接近 于 “step by step” 的 学 习 方 式 ， 我 在 写作 这 一 部 分 
时 ， 会 通过 循序 渐进 的 方式 使 读者 能 够 快速 上 手 ， 同 时 会 罕 插 着 介绍 其 


常见 用 法 的 基本 原理 。 


在 第 三 部 分 ， 将 开始 介绍 Nginx 的 完整 框 染 ， 阅 读 到 这 里 将 会 了 解 
二 部 分 中 HTTP 模 块 为 何以 此 种 方式 开 及 ， 同 时 将 可 以 轻易 地 开 友 
Nginx 模 块 。 这 一 部 分 并 不 仅仅 满足 于 阐述 Nginx 架 构 ， 而 是 会 探讨 其 为 
何如 此 设计 ， 只 有 这 样 才 能 抛 开 HITP 框 架 、 邮 件 代 理 框架 ， 实 现 一 种 

新 的 业务 框架 、 一 种 新 的 模块 类 型 。 





对 于 Nginx 的 使 用 还 不 熟悉 的 读者 应 当 从 第 1 章 开 始 学 习 ， 前 两 章 将 
帮助 你 快速 了 解 Nginx。 


使 用 过 Nginx， 但 对 如 何 开发 Nginx 的 HTTP 模 块 不 太 了 解 的 读者 可 





以 直接 从 第 3 音 开 始 学 习 ， 在 这 一 章 阅 读 完 后 ， 即 可 编写 一 个 功能 大 致 
完整 的 HTTP 模 块 。 然 而 ， 编 写 企业 级 的 模块 必须 阅读 完 第 4 章 才 能 做 
到 ， 这 一 章 将 会 介绍 编写 产品 线 上 服务 占 程 序 时 必 备 的 3 个 手段 。 第 5 章 
举例 说 明了 两 种 编写 复杂 HTTP 模 块 的 方式 ， 在 第 三 部 分 会 对 这 两 个 方 
式 有 进一步 的 说 明 。 第 6 半 介 绍 一 种 特殊 的 HTTP 模 块 一 一 HTTP 过 小 模 
块 的 编写 方法 。 第 7 章 探 讨 基础 容 圳 的 用 法 ， 这 同样 是 复杂 模块 的 必 备 
本 

















如 果 读者 对 于 普通 HTTP 模 块 的 编写 已 经 很 熟悉 ， 想 深入 地 实现 更 
为 复杂 的 HITP 模 块 ， 或 者 想 了 解 邮件 代理 服务 器 的 设计 与 实现 ， 或 者 
希望 编写 一 种 新 的 处 理 其 他 协议 的 模块 ， 或 者 仅仅 想 了 解 Nginx 的 架构 
设计 ， 都 可 以 直接 从 第 8 章 开 始 学 习 ， 这 一 章 会 从 整体 上 系统 介绍 Nginx 
的 模块 式 设计 。 第 9 章 的 事件 框架 是 Nginx 处 理 TCP 的 基础 ， 这 一 章 无 法 
跳 过 。 阅 读 第 8 章 、 第 9 章 时 可 能 会 遇 到 许多 第 7 章 介绍 过 的 容器 ， 这 时 
可 以 回 到 第 7 章 查 询 其 用 法 和 意义 。 第 10 章 ~ 第 12 章 在 介绍 HTTP 框架， 
通过 这 3 章 的 学 习 会 对 HTTP 模 块 的 开发 有 深入 的 了 解 ， 同 时 可 以 学 习 
HTTP 框 架 的 优秀 设计 。 第 13 章 简单 介绍 了 邮件 代理 服务 絮 的 设计 ， 它 
近似 于 简化 版 的 HTTP 框 架 。 第 14 章 介绍 了 进程 间 同 步 的 工具 。 第 15 章 
介绍 了 HTTP 变 量 ， 包 括 如 何 使 用 已 有 变量 、 支 持 用 户 在 nginx.conf 中 修 
改变 量 的 值 、 文 持 其 他 模块 开发 者 使 用 自己 定义 的 变量 等 。 第 16 章 介绍 
了 slab 共 享 内 存 ， 该 内 存 极为 高 效 ， 可 用 于 多 个 worker 进 程 间 的 通信 。 


























为 了 不 让 读者 陷入 代码 的 “汪洋 大 海 * 中 ， 在 本 书 中 大 量 使 用 了 图 
表 ， 这 样 可 以 使 读者 快速 、 大 体 地 了 解 流 程 和 原理 ， 在 这 基础 上 ， 如 果 
读者 还 希望 了 解 代码 是 如 何 实现 的 ， 可 以 针对 性 地 阅读 源 代码 中 的 相应 
方法 。 在 代码 的 关键 地 方 会 通过 添加 注释 的 方式 加 以 说 明 。 希 望 这 种 方 
式 能 够 帮助 读者 减少 阅读 花费 的 时 间 ， 更 快 、 更 好 地 把 握 住 Nginx， 同 
时 深入 到 细节 中 。 











写作 本 书 第 1 版 时 ，Nginx 的 最 新 稳定 版 本 是 1.0.14， 所 以 当时 是 基 
于 此 版 本 来 写作 的 。 截 止 到 第 2 版 完成 时 ，Nginx 的 稳定 版 本 已 经 上 升 到 
了 1.8.0。 但 这 不 会 对 本 书 的 阅读 造成 困惑 ， 笔 者 验证 过 示例 代码 ， 均 可 
以 运行 在 最 新 版 本 的 Nginx 中 ， 这 是 因为 本 书 主要 是 在 介绍 Nginx 的 基本 
框架 代码 ， 以 及 怎样 使 用 这 些 框架 代码 开 友 新 的 Nginx 模 块 。 在 这 些 基 
本 框架 代码 中 ，Nginx 一 般 不 会 做 任何 改变 ， 人 否则 已 有 的 大 量 Nginx 模 块 
将 无 法 工作 ， 这 种 损失 是 不 可 承受 的 。 而 且 Nginx 框 架 为 具体 的 功能 模 
块 提 供 了 足够 的 灵活 性 ， 修 改 功 能 时 很 少 需 要 修改 框架 代码 。 


Nginx 是 跨 平 台 的 服务 器 ， 然 而 这 本 书 将 只 针对 于 最 第 见 的 Linux 操 
作 系 统 进行 分 析 ， 这 样 做 一 方面 是 篇 幅 所 限 ， 为 一 方面 则 是 本 书 的 写作 
目的 主要 在 于 告诉 大 家 如 何 基于 Nginx 编 写 代 码 ， 而 不 是 怎样 在 一 个 具 
体 的 操作 系统 上 修改 配置 使 用 Nginx。 因 此 ， 即 使 本 书 以 Linux 系 统 为 代 
表 讲 述 Nginx， 也 不 会 影响 使 用 其 他 操作 系统 的 读者 阅读 ， 操 作 系 统 的 
差别 相对 于 本 书 内 容 的 影响 实在 是 非常 小 。 











勘误 和 支持 


由 于 作者 的 水 平 有 限 ， 加 之 编写 的 时 间 也 很 仓促 ， 书 中 难免 会 出 现 
一 些 错 误 或 者 不 准确 的 地 方 ， 奶 请 读者 批评 指正 。 为 此 ， 我 特意 创建 了 
一 个 在 线 支 持 与 应 急 方案 的 二 级 站 点 : http://nginx.weebly.com 。 读 者 可 
以 将 书 中 的 错误 发 布 在 Bug 勘 误 表 页 面 中 ， 同 时 如 果 读 者 遇 到 任何 问 
题 ， 也 可 以 访问 Q&A 页 面 ， 我 将 尽量 在 线 上 为 读者 提供 最 满意 的 解 
答 。 书 中 的 全 部 源 文件 都 将 发 布 在 这 个 网 站 上 ， 我 也 会 将 相应 的 功能 
新 及 时 发 布 出 来 。 如 果 你 有 更 多 的 宝贵 意见 ， 也 欢迎 你 发 送 邮件 至 我 的 


邮箱 russelltao@foxmail.com， 期 符 能 够 听 到 读者 的 真挚 反馈 。 














致谢 


我 首先 要 感谢 Igor Sysoev， 他 在 Nginx 设 计 上 展现 的 功力 令 人 折 
服 ， 正 是 他 的 工作 成 果 才 有 了 本 书 诞生 的 意义 。 


lisa 是 机 械 工 业 出 版 社 华章 公司 的 优秀 编辑 ， 非 常 值得 信任 。 在 这 
半年 的 写作 过 程 中 ， 她 花费 了 很 多 时 间 、 精 力 来 阅读 我 的 书稿 ， 指 出 了 
许多 文字 上 和 格式 上 的 错误 ， 她 提出 的 建议 都 大 大 提高 了 本 书 的 可 读 
任 5 





在 这 半年 时 间 里 ， 一 边 工作 一 边 写 作 给 我 带 来 了 很 大 的 压力 ， 所 以 
我 要 感谢 我 的 父母 在 生活 上 对 我 无 微 不 至 的 照顾 ， 使 我 可 以 全 力 投 入 到 


写作 中 。 索 忙 的 工作 之 余 ， 写 作 又 占用 了 休 奶 时 间 的 绝 大 部 分 ， 感 谢 我 
的 太太 毛 业 勤 对 我 的 体谅 和 鼓励 ， 让 我 始终 以 高 昂 的 斗志 投入 到 本 书 的 
写作 中 。 





感谢 我 工作 中 的 同事 们 ， 正 是 在 与 他 们 一 起 战斗 在 一 线 的 日 子 里 ， 
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三 大 


第 一 部 分 “Nginx 能 帮 我 们 做 什么 
. 第 1 章 ”研究 Nginx 前 的 准备 工作 


` 第 2 章 Neginx 的 配置 


第 l 章 ”研究 Nginx 前 的 准备 工作 


2012 年 ，Nginx 订 获 年 度 云 计 算 开 发 奖 (2012 Cloud Award for 
Developer of the Year) ， 并 成 长 为 世界 第 二 大 Web 服 务 器 。 全 世界 流量 
最 高 的 前 1000 名 网 站 中 ， 超 过 25% 都 使 用 Nginx 来 处 理 海量 的 互联 网 请 
求 。Nginx 已 经 成 为 业界 高 性 能 web 服务 器 的 代名词 。 





那么 ， 什 么 是 Nginx? 它 有 哪些 特点 ? 我 们 选择 Nginx 的 理由 是 什 
么 ? 如 何 编译 安装 Nginx? 这 种 安装 方式 背后 隐藏 的 又 是 什么 样 的 思想 


呢 ? 本 章 将 会 回答 上 述 问题 。 





1.1 Nginx 是 什么 


人 们 在 了 解 新 事物 时 ， 人 往往 习 惯 通过 类 比 来 帮助 自己 理解 事物 的 概 
貌 。 那 么 ， 我 们 在 学 习 Nginx 时 也 采用 同样 的 方式 ， 先 来 看 看 Nginx 的 竞 
争 对 手 一 一 Apache、Lighttpd、Tomcat、Jetty、IIS， 它 们 都 是 Web 服 务 
器 ， 或 者 叫做 WWW (World Wide Web) 服务 器 ， 相 应 地 也 都 具备 Web 
服务 器 的 基本 功能 : 基于 REST 架 构 风 格 和 1 ， 以 统一 资源 描述 符 
(Uniform Resource Identifier，URI) 或 者 统一 资源 定位 符 (Uniform 
Resource Locator，URL) 作为 沟通 依据 ， 通 过 HTTP 为 浏览 絮 等 客户 端 
程序 提供 各 种 网 络 服务 。 然 而 ， 由 于 这 些 Web 服 务 器 在 设计 阶段 就 受到 
许多 局 限 ， 例 如 当时 的 互联 网 用 户 规模 、 网 络 带宽 、 产 品 特点 等 局 限 ， 
并 且 各 自 的 定位 与 发 展 方向 都 不 尽 相 同 ， 使 得 每 一 款 Web 服 务 器 的 特点 
与 应 用 场合 都 很 鲜明 。 








Tomcat 和 Jetty 面 同 Java 语 言 ， 先 天 束 是 重量 级 的 Web 服 务 嚣 ， 它 的 
性 能 与 Nginx 没 有 可 比 性 ， 这 里 略 过 。 


IIS 只 能 在 Windows 操 作 系 统 上 运行 。Windows 作 为 服务 器 在 稳定 性 
与 其 他 一 些 性 能 上 都 不 如 类 UNIX 操 作 系 统 ， 因 此 ， 在 需要 高 性 能 Web 
服务 器 的 场合 下 ，IIS 可 能 会 被 “冷落 ”。 








Apache 的 发 展 时 期 很 长 ， 而 且 是 目前 坚 无 争议 的 世界 第 一 大 Web 服 


务 器 ， 图 1-1 中 是 12 年 来 (2010~2012 年 ) 世界 web 服务 器 的 使 用 排名 情 
ms 
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图 1-1 Netctaft 对 于 644275754 个 站 点 31.4M 个 域名 Web 服 务 器 使 用 情况 的 
调查 结果 (2012 年 3 月 ) 


从 图 1-1 中 可 以 看 出 ，Apache 目 前 处 于 领先 地 位 。 


Apache 有 许多 优点 ， 如 稳定 、 开 源 、 蜂 平台 等 ， 但 它 出 现 的 时 间 太 
长 了 ， 在 它 兴 起 的 年 代 ， 互 联网 的 产业 规模 远 远 比 不 上 今天 ， 所 以 它 被 
设计 成 了 一 个 重量 级 的 、 不 支持 高 并 发 的 Web 服 务 嚣 。 在 Apache 服 务 器 
上 ， 如 果 有 数 以 万 计 的 并 发 HTTP 请 求 同 时 访问 ， 就 会 导致 服务 器 上 消 
耗 大 量 内 存 ， 操 作 系 统 内 核对 成 百 上 于 的 Apache 进 程 做 进程 间 切 换 也 会 
消耗 大 量 CPU 资 源 ， 并 导致 HTTP 请 求 的 平均 响应 速度 降低 ， 这 些 都 决 


定 了 Apache 不 可 能 成 为 高 性 能 web 服务 器 ， 这 也 促使 了 Lighttpd 和 Nginx 
的 出 现 。 观 察 图 1-1 中 Nginx 成 长 的 曲线 ， 体 会 一 下 Nginx 抢 占 市 场 时 
的 “ 员 吊 逼 人 2” 吧 。 


Lighttpd 和 Nginx 一 样 ， 都 是 轻 量 级 、 高 性 能 的 web 服务 器 ， 欧 美的 
业界 开发 者 比较 钟爱 Lighttpd， 而 国内 的 公司 更 青睐 Nginx，Lighttpd 使 
用 得 比较 少 。 





在 了 解 了 Nginx 的 苋 争 对 手 之 后 ， 相 信 大 家 对 Nginx 也 有 了 直观 感 
受 ， 下 面 让 我 们 来 正式 地 认识 一 下 Nginx 吧 。 


iQ 提示 Nginx 发 音 : enginel :Nd3in] X 5 
来 自 俄 罗斯 的 Igor Sysoev 在 为 Rambler 
Media (http:/www.rambler.ru/ ) 工作 期 间 ， 使 用 C 语 言 开 发 了 Nginx。 


Nginx 作 为 Web 服 务 器 ， 一 直 为 俄罗斯 善 名 的 门户 网 站 Rambler Media 提 
供 着 出 色 、 稳 定 的 服务 。 





Igor Sysoev 将 Nginx 的 代码 开源 ， 并 且 赋 予 其 最 自由 的 2-clause BSD- 
like license 号 许可 证 。 由 于 Nginx 使 用 基于 事件 驱动 的 架构 能 够 并 发 处 
理 百 万 级 别 的 TCP 连 接 ， 高 度 模块 化 的 设计 和 自由 的 许可 证 使 得 扩展 
Nginx 功 能 的 第 三 方 模块 层出不穷 ， 而 且 优 秀 的 设计 带 来 了 极 佳 的 稳定 
性 ， 因 此 其 作为 Web 服 务 器 被 广泛 应 用 到 大 流量 的 网 站 上 ， 包 括 腾 讯 、 
新 浪 、 网 易 、 淘 宝 等 访问 量 巨 大 的 网 站 。 











2012 年 2 月 和 3 月 Netcraft 对 Web 服 务 器 的 调查 如 表 1-1 所 示 ， 可 以 看 
出 ，Nginx 的 市 场 份 额 越 来 越 大 。 


表 1-1 Netctaft 对 于 Web 服 务 器 市 场 占 有 率 前 4 位 软件 的 调查 〈2012 年 2 月 
和 3 月 ) 


TI 有 有 
Microsoft IIS 22 537 872 -0.06 
Google WebServer | 14316485 | 77% | 14438358 | 76% | _-00 





Nginx 是 一 个 跨 平 台 的 Web 服 务 嚣 ， 可 运行 在 Linux、FreeBSD、 
Solaris、AIX、Mac OS、Windows 等 操作 系统 上 ， 并 且 它 还 可 以 使 用 当 
前 操作 系统 特有 的 一 些 高 效 API 来 提高 自己 的 性 能 。 


例如 ， 对 于 高 效 处 理 大 规模 并 发 连接 ， 它 文 持 Linux 上 的 
epoll (epoll 是 Linux 上 处 理 大 并 发 网 络 连 接 的 利器 ，9.6.1 节 中 将 会 详细 
说 明 epoll 的 工作 原理 ) 、Solaris 上 的 event ports 和 FreeBSD 上 的 kqueue 


有 
等 。 


又 如 ， 对 于 Linux，Nginx 支 持 其 独 有 的 sendfile 系 统 调用 ， 这 个 系统 
调用 可 以 高 效 地 把 硬盘 中 的 数据 发 送 到 网 络 上 不 需要 先 把 硬盘 数据 复 
制 到 用 户 态 内 存 上 再 发 送 ) ， 这 极 大 地 减少 了 内 核 态 与 用 户 态 数据 间 的 
复制 动作 。 





种 种 迹象 都 表明 ，Nginx 以 性 能 为 王 。 


2011 年 7 月 ，Nginx 正 式 成 立 公 司 ， 由 Igor Sysoev 担 任 CTO， 工 足 于 
提供 商业 级 的 Web 服 务 器 。 


[1] 参见 Roy Fielding 博 士 的 论文 《Atchitectutal Styles and the Design of 
Network-based Software Atrchitectures》， 可 在 http://www.ics.uci.edu/~f 
ielding/pubs/dissertation/top.htm 查 看 原文 。 
2] BSD (Berkeley Software Disttibution) 许可 协议 是 自由 软件 (开源 软件 
的 一 个 子 集 ) 中 使 用 最 广泛 的 许可 协议 之 一 。 与 其 他 许可 协议 相 比 ， 
BSD 许 可 协议 从 GNU 通 用 公共 许可 协议 〈GPL) 到 限制 重重 的 著作 权 
(copyright) 都 要 宽松 一 些 ， 事 实 上 ， 它 跟 公 有 领域 更 为 接近 。BSD 许 
可 协议 被 认为 是 copycenter (中 间 版 权 ) ， 界 于 标准 的 copytight 与 GPL 的 
copyleft 之 间 。2-clause BSD-like license 是 BSD 许 可 协议 中 最 宽松 的 一 种 ， 
它 对 开发 者 再 次 使 用 BSD 软 件 只 有 两 个 基本 的 要 求 : 一 是 如 果 再 发 布 的 
产品 中 包含 源 代 码 ， 则 在 源 代码 中 必须 带 有 原来 代码 中 的 BSD 协 议 ; 二 
是 如 果 再 发 布 的 只 是 二 进 制 类 库 / 软 件 ， 则 需要 在 类 库 / 软 件 的 文档 和 版 
权 声 明 中 包含 原来 代码 中 的 BSD 协 议 。 


1.2 为 什么 选择 Nginx 





为 什么 选择 Nginx? 因为 它 具 有 以 下 特点 : 


(1) 更 快 





这 表现 在 两 个 方面 : 一 方面 ， 在 正常 情况 下 ， 单 次 请 求 会 得 到 更 快 
的 啊 应 ; 男 一 方 和 面 ， 在 高 峰 期 (如 有 数 以 万 计 的 并 友 请 求 ) ，Nginx 可 
以 比 其 他 Web 服 务 占 更 快 地 啊 应 请 求 。 





实际 上 ， 本 书 第 三 部 分 中 大 量 的 篇 幅 都 是 在 说 明 Nginx 是 如 何 做 到 
这 两 点 的 。 


(2) 高 扩展 性 





Nginx 的 设计 极 具 扩展 性 ， 它 完全 是 由 多 个 不 同 功能 、 不 同 层次 、 
不 同类 型 且 耦 合 度 极 低 的 模块 组 成 。 因 此 ， 当 对 某 一 个 模块 修复 Bug 或 
进行 升级 时 ， 可 以 专注 于 模块 自身 ， 无 须 在 意 其 他 。 而 且 在 HITP 模 块 
中 ， 还 设计 了 HTTP 过 滤器 模块 : 一 个 正常 的 HTTP 模 块 在 处 理 完 请 求 
后 ， 会 有 一 串 HITP 过 滤器 模块 对 请 求 的 结果 进行 再 处 理 。 这 样 ， 当 我 
们 开发 一 个 新 的 HTTP 模 块 时 ， 不 但 可 以 使 用 诸如 HTTP 核 心 模块 、 
events 模 块 、log 模 块 等 不 同 层次 或 者 不 同类 型 的 模块 ， 还 可 以 原封 不 动 
地 复 用 大 量 已 有 的 HITP 过 滤器 模块 。 这 种 低 耘 合 度 的 优秀 设计 ， 造 就 











了 Nginx 庞 大 的 第 三 方 模块 ， 当 然 ， 公 开 的 第 三 方 模块 也 如 官方 发 布 的 
模块 一 样 容 易 使 用 。 


Nginx 的 模块 部 是 舱 入 到 二 进 制 文件 中 执行 的 ， 无 论 官方 发 布 的 模 
块 还 是 第 三 方 模块 都 是 如 此 。 这 使 得 第 三 方 模块 一 样 共 备 极其 优秀 的 性 
能 ， 充 分 利用 Nginx 的 高 并 发 特性 ， 因 此 ， 许 多 高 流量 的 网 站 都 倾向 于 
开发 符合 目 己 业务 特性 的 定制 模块 。 














(3) 高 可 靠 性 


高 可 靠 性 是 我 们 选择 Nginx 的 最 基本 条 件 ， 因 为 Nginx 的 可 靠 性 是 大 
家 有 目 共 睹 的 ， 很 多 家 高 流量 网 站 都 在 核心 服务 器 上 大 规模 使 用 
Nginx。Nginx 的 高 可 靠 性 来 自 于 其 核心 框架 代码 的 优秀 设计 、 模 块 设计 
的 简单 性 ， 另外， 官方 提供 的 常用 模块 都 非常 稳定 ， 每 个 worker 进 程 相 
对 独立 ，master 进 程 在 1 个 worker 进 程 出 错时 可 以 快速 “ 拉 起 ”新 的 worker 
子 进程 提供 服务 。 














(4) 低 内 存 消耗 


一 般 情况 下 ，10000 个 非 活 跃 的 HTTP Keep-Alive 连 接 在 Nginx 中 仪 
消耗 2.5MB 的 内 存 ， 这 是 Nginx 支 持 高 并 发 连接 的 基础 。 


从 第 3 章 开 始 ， 我 们 会 接触 到 Nginx 在 内 存 中 为 了 维护 一 个 HTTP 连 
接 所 分 配 的 对 象 ， 届 时 将 会 看 到 ， 实 际 上 Nginx 一 直 在 为 用 户 考 虑 ( 尤 





其 是 在 高 并 发 时 ) 如 何 使 得 内 存 的 消耗 更 少 。 


(5) 单机 支持 10 万 以 上 的 并 发 连接 





这 是 一 个 非常 重要 的 特性 ! 随 着 互联 网 的 迅猛 发 展 和 互联 网 用 户 数 
量 的 成 倍增 长 ， 各 大 公司 、 网 站 都 需要 应 付 海量 并 发 请 求 ， 一 个 能 够 在 
峰值 期 顶 住 10 万 以 上 并 发 请 求 的 Server， 无 疑 会 得 到 大 家 的 青睐 。 理 论 
上 ，Nginx 文 持 的 并 发 连接 上 限 取决 于 内 存 ，10 万 远 示 封顶。 当然， 能 
够 及 时 地 处 理 更 多 的 并 发 请 求 ， 是 与 业务 特点 紧密 相关 的 ， 本 书 第 8~11 
草 将 会 详细 说 明 如 何 实现 这 个 特点 。 














(6) 热 部 署 


master 管 理 进 程 与 worker 工 作 进 程 的 分 离 设 计 ， 使 得 Nginx 能 够 提供 
热 部 署 功能 ， 即 可 以 在 7x24 小 时 不 间断 服务 的 前 提 下 ， 升 级 Nginx 的 可 
执行 文件 。 当 然 ， 它 也 文 持 不 停止 服务 就 更 新 配置 项 、 更 换 日 志文 件 等 


功能 。 


(7) 最 自由 的 BSD 许 可 协议 





这 是 Nginx 可 以 快速 发 展 的 强大 动力 。BSD 许 可 协议 不 只 是 允许 用 
户 免费 使 用 Nginx， 它 还 允许 用 户 在 目 己 的 项 目 中 直接 使 用 或 修改 Nginx 
源码 ， 然 后 发 布 。 这 吸引 了 无 数 开发 者 继续 为 Nginx 页 献 目 己 的 知 意 。 





以 上 7 个 特点 当然 不 是 Nginx 的 全 部 ， 拥 有 无 数 个 官方 功能 模块 、 第 


三 方 功能 模块 使 得 Nginx 能 够 满足 绝 大 部 分 应 用 场景 ， 这 些 功能 模块 间 
可 以 车 加 以 实现 更 加 强大 、 复 杂 的 功能 ， 有 些 模块 还 支持 Nginx 与 Perl、 
Lua 等 脚本 语言 集成 工作 ， 大 大 提高 了 开发 效率 。 这 些 特点 促使 用 户 在 
寻找 一 个 Web 服 务 器 时 更 多 考虑 Nginx。 








当然 ， 选 择 Nginx 的 核心 理由 还 是 它 能 在 文 持 高 并 发 请 求 的 同时 保 
持 高 效 的 服务 。 


如 果 Web 服 务 器 的 业务 访问 量 巨大 ， 就 需要 保证 在 数 以 百 万 计 的 请 
求 同 时 访问 服务 时 ， 用 户 可 以 获得 恨 好 的 体验 ， 不 会 出 现 并 发 访问 量 达 
到 一 个 数字 后 ， 新 的 用 户 无 法 获取 服务 ， 或 者 虽然 成 功 地 建立 起 了 TCP 
连接 ， 但 大 部 分 请 求 却 得 不 到 啊 应 的 情况 。 





通常 ， 高 峰 期 服务 器 的 访问 量 可 能 是 正常 情况 下 的 许多 倍 ， 行 有 热 
点 事件 的 发 生 ， 可 能 会 导致 正 闻 情况 下 非常 顺畅 的 服务 器 直接 “ 挂 死 ”。 
然而 ， 如 果 在 部 署 服务 右 时 ， 束 预先 针对 这 种 情况 进行 扩容 ， 又 会 使 得 
正常 情况 下 所 有 服务 器 的 负载 过 低 ， 这 会 造成 大 量 的 资源 浪费 。 因 此 ， 
我 们 会 希望 在 这 之 间 取 得 平衡 ， 也 就 是 说 ， 在 低 并 发 压力 下 ， 用 户 可 以 
获得 高 速 体验 ， 而 在 高 并 发 压力 下 ， 更 多 的 用 户 都 能 接 入 ， 可 能 访问 速 
度 会 下 降 ， 但 这 只 应 受制 于 带宽 和 处 理 器 的 速度 ， 而 不 应 该 是 服务 器 设 
计 导 致 的 软件 瓶颈 。 


事实 上 ， 由 于 中 国 互联 网 用 户 群 体 的 数量 巨大 ， 致 使 对 Web 服 务 咒 


的 设计 往往 要 比 欧美 公司 更 加 困难 。 例 如 ， 对 于 全 球 性 的 一 些 网 站 而 
， 欧 美 用 户 分 布 在 两 个 半球 ， 欧 洲 用 户 活跃 时 ， 美 洲 用 户 通常 在 休 
， 友 之 亦 然 。 而 国内 巨大 的 用 户 和 群体 则 对 业界 的 程序 员 提出 更 高 的 挑 
战 ， 早 上 9 点 和 晚上 20 点 到 24 点 这 些 时 间 段 的 并 发 请 求 压 力 是 非常 巨大 
的 。 无 其 节假日 、 寒 晋 假 到 来 之 时 ， 更 会 对 服务 器 提出 极 高 的 要 求 。 
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另外 ， 国 内 业务 上 的 特性 ， 也 会 引导 用 户 在 同一 时 间 大 并 发 地 访问 
服务 器 。 例 如 ， 许 多 SNS 网 页 游戏 会 在 固定 的 时 间 点 刷新 游戏 资源 或 者 
允许 " 偷 菜 "等 好 友 互 动 操作 。 这 些 会 导致 服务 器 处 理 高 并 发 请 求 的 压力 
增 大 。 





上 述 情形 都 对 我 们 的 互联 网 服务 在 大 并 发 压力 下 是 人 否 还 能 够 给 予 用 
户 民 好 的 体验 提出 了 更 高 的 要 求 。 在 要 提供 更 好 的 服务 ， 那 么 可 以 从 多 
方面 入 手 ， 例 如 ， 修 改 业 务 特性 、 引 导 用 户 从 高 峰 期 分 流 或 者 把 服务 分 
层 分 级 、 对 于 不 同 并 发 压力 给 用 户 提供 不同 级 别 的 服务 等 。 但 最 根本 的 
是 ，Web 服 务 器 要 能 文 持 大 并 发 压力 下 的 正常 服务 ， 这 才 古 关键 。 


快速 增长 的 互联 网 用 户 群 以 及 业内 所 有 互联 网 服务 提供 商 越 来 越 好 
的 用 户 体验 ， 都 促使 我 们 在 大 流量 服务 中 用 Nginx 取 代 其 他 Web 服 务 
器 。Nginx 先 天 的 事件 驱动 型 设计 、 全 异步 的 网 络 IJO 处 理 机 制 、 极 少 的 
进程 间 切 换 以 及 许多 优化 设计 ， 都 使 得 Nginx 天 生 善 于 处 理 高 并 发 压力 
下 的 互联 网 请 求 ， 同 时 Nginx 降 低 了 资源 消耗 ， 可 以 把 服务 器 硬件 资 
源 “ 压 榨 ” 到 极致 。 





1.3 ”准备 工作 


由 于 Linux 具 有 免费 、 使 用 广泛 、 商 业 文 持 越 来 越 完善 等 特点 ， 本 
书 将 主要 针对 Linux 上 运行 的 Nginx 来 进行 介绍 。 需 要 说 明 的 是 ， 本 书 不 
是 使 用 手册 ， 而 是 介绍 Nginx 作 为 Web 服 务 器 的 设计 思想 ， 以 及 如 何 更 
有 效 地 使 用 Nginx 达 成 目的 ， 而 这 些 内 容 在 各 操作 系统 上 基本 是 相通 的 
《除了 第 9 章 关 于 事件 驱动 方式 以 及 第 14 章 的 进程 间 同 步 方式 在 类 UNIX 
操作 系统 上 略 有 不 同 以 外 ) 。 





1.3.1 Linux 操 作 系 统 


首先 我 们 需要 一 个 内 核 为 Linux 2.6 及 以 上 版 本 的 操作 系统 ， 因 为 
Linux 2.6 及 以 上 内 核 才 支持 epoll， 而 在 Linux 上 使 用 select 或 poll 来 解决 事 
件 的 多 路 复 用 ， 是 无 法 解决 高 并 发 压力 问题 的 。 


我 们 可 以 使 用 uname-a 命 令 来 查询 Linux 内 核 版 本 ， 例 如 : 





:wehf2wng001:root > uname -a 
Linux wehf2wng001 2.6.18-128.el5 #1 SMP Wed Jan 21 10:41:14 EST 2009 x86_64 x86_64 》 





执行 结果 表明 内 核 版 本 是 2.6.18， 符 合 我 们 的 要 求 。 


1.3.2 ”使 用 Nginx 的 必 备 软件 


如 果 要 使 用 Nginx 的 第 用 功能 ， 那 么 首先 需要 确保 该 操作 系统 上 至 
少 安 装 了 如 下 软件 。 


(1) GCC 编译 器 


GCC (GNU Compiler Collection) 可 用 来 编译 C 语 言 程序 。Nginx 不 
会 直接 提供 二 进 制 可 执行 程序 〈1.2.x 版 本 中 已 经 开始 提供 某 些 操作 系统 
上 的 二 进 制 安装 包 了 ， 不 过 ， 本 书 探讨 如 何 开 发 Nginx 模 块 是 必须 通过 
直接 编译 源 代 码 进行 的 ) ， 这 有 许多 原因 ， 本 章 后 面 会 详 述 。 我 们 可 以 
使 用 最 简单 的 yum 方 式 安装 GCC， 例 如 : 








yum install -y gcc 











GCC 是 必需 的 编译 工具 。 在 第 3 章 会 提 到 如 何 使 用 C++ 来 编写 Nginx 
HITP 模 块 ， 这 时 就 需要 用 到 G++ 编 译 器 了 。G++ 编 译 吉 也 可 以 用 yum 安 
装 ， 例如 : 





yum install -y gcc-c++ 





Linux 上 有 许多 软件 安装 方式 ，yum 只 是 其 中 比较 方便 的 一 种 ， 其 他 
方式 这 里 不 再 痪 述 。 


(2) PCRE 库 


PCRE (Perl Compatible Regular Expressions，Perl 兼 容 正 则 表达 式 ) 





是 由 Philip Hazel 开 发 的 函数 库 ， 目 前 为 很 多 软件 所 使 用 ， 该 库 支 持 正 则 
表达 式 。 它 由 RegEx 演 化 而 来 ， 实 际 上 ，Perl 正 则 表达 式 也 是 源 自 于 
Henry Spencer 写 的 RegEx。 


如 果 我 们 在 配置 文件 nginx.conf 里 使 用 了 正则 表达 式 ， 那 么 在 编译 
Nginx 时 就 必须 把 PCRE 库 编译 进 Nginx， 因 为 Nginx 的 HITP 模 块 要 靠 它 
来 解析 正则 表达 式 。 当 然 ， 如 果 你 确认 不 会 使 用 正则 表达 式 ， 就 不 必 安 
装 它 。 其 yum 安 装 方式 如 下 : 





yum install -y pcre pcre-devel 








pcre-devel 是 使 用 PCRE 做 二 次 开发 时 所 需要 的 开发 库 ， 包 括 头 文件 
等 ， 这 也 是 编译 Nginx 所 必须 使 用 的 。 


(3) zlib 库 


zlib 库 用 于 对 HTTP 包 的 内 容 做 gzip 格 式 的 压缩 ， 如 果 我 们 在 
nginx.conf 里 配置 了 gzip on， 并 指定 对 于 某 些 类 型 (content-type) 的 
HTTP 啊 应 使 用 gzip 来 进行 压缩 以 减少 网 络 传输 量 ， 那 么 ， 在 编译 时 残 
必须 把 zlib 编 译 进 Nginx。 其 yum 安 装 方式 如 下 : 





yum install -y zlib zlib-devel 





同 理 ，zlib 是 直接 使 用 的 库 ，zlib-devel 是 二 次 开发 所 需要 的 库 。 


(4) OpenSSL 开 发 库 


如 果 我 们 的 服务 器 不 只 是 要 支持 HITP， 还 需要 在 更 安全 的 SSL 协 
议 上 传输 HTTP， 那 么 就 需要 拥有 OpenSSL 了。 另外 ， 如 果 我 们 想 使 用 
MD5、SHA1 等 散 列 函 数 ， 那 么 也 需要 安装 它 。 其 yum 安 装 方 式 如 下 : 


yum install -y openssl openssl-devel 





上 面 所 列 的 4 个 库 只 是 完成 Web 服 务 器 最 基本 功能 所 必需 的 。 


Nginx 是 高 度 目 由 化 的 web 服务器 ， 它 的 功能 是 由 许多 模块 来 文 持 
的 。 而 这 些 模块 可 根据 我 们 的 使 用 需求 来 定制 ， 如 果 菏 些 模块 不 需要 使 
用 则 完全 不 必 理 会 它 。 同 样 ， 如 宁 使 用 了 东 个 模块 ， 而 这 个 模块 使 用 了 
一 些 类 似 zlib 或 OpenSSL 等 的 第 三 方 库 ， 那 么 就 必须 先 安装 这 些 软件 。 


1.3.3 ”磁盘 目录 


要 使 用 Nginx， 还 需要 在 Linux 文 件 系统 上 准备 以 下 目录 。 
(1) Nginx 源 代码 存放 目录 


该 目录 用 于 放置 从 官网 上 下 载 的 Nginx 源 码 文件 ， 以 及 第 三 方 或 我 
们 目 己 所 写 的 模块 源 代码 文件 。 


(2) Nginx 编 译 阶段 产生 的 中 间 文 件 存 放 目 录 


该 目录 用 于 放置 在 configure 命 令 执行 后 所 生成 的 源 文件 及 目录 ， 以 
及 make 命 令 执行 后 生成 的 目标 文件 和 最 终 连 接 成 功 的 二 进 制 文件 。 默 认 
情况 下 ，configure 命 令 会 将 该 目录 命名 为 objs， 并 放 在 Nginx 源 代码 目录 
下 


(3) 部 署 目 录 








该 目录 存放 实际 Nginx 服 务 运行 期 间 所 需要 的 二 进 制 文件 、 配 置 文 
件 等 。 默 认 情 况 下 ， 该 目录 为 /usr/local/nginx。 


(4) 日 志文 件 存 放 目 录 


日 志文 件 通 常会 比较 大 ， 当 研究 Nginx 的 底层 架构 时 ， 需 要 打开 
debug 级 别 的 日 志 ， 这 个 级 别 的 日 志 非 党 详细， 会 导致 日 志文 件 的 大 小 
增长 得 极 快 ， 需 要 预先 分 配 一 个 拥有 更 大 磁盘 空间 的 目录 。 





1.3.4 Linux 内 核 参数 的 优化 


由 于 默认 的 Linux 内 核 参数 考虑 的 是 最 通用 的 场景 ， 这 明显 不 符合 
用 于 文 持 高 并 发 访问 的 Web 服 务 器 的 定义 ， 所 以 需要 修改 Linux 内 核 参 
数 ， 使 得 Nginx 可 以 拥有 更 高 的 性 能 





在 优化 内 核 时 ， 可 以 做 的 事情 很 多 ， 不 过 ， 我 们 通常 会 根据 业务 特 
点 来 进行 调整 ， 当 Nginx 作 为 静态 Web 内 容 服务 器 、 反 向 代理 服务 器 或 


是 提供 图 片 缩 略图 功能 〈 实 时 压缩 图 片 ) 的 服务 器 时 ， 其 内 核 参数 的 调 
整 都 是 不 同 的 。 这 里 只 针对 最 通用 的 、 使 Nginx 支 持 更 多 并 发 请 求 的 
TCP 网 络 参数 做 简单 说 明 。 





首先 ， 需 要 修改 /etc/sysctl.conf 来 更 改 内 核 参 数 。 例 如 ， 最 常用 的 配 


置 : 





fs.file-max = 999999 





net.Ipv4.tcp_tw_reuse = 工 
net.ipv4.tcp_keepalive time = 600 
net.Ipv4.tcp_fin_timeout = 30 
net.Ipv4.tcp_max_tw_buckets = 5000 
net.ipv4.ip_local port_range = 1024 61000 
net.ipv4.tcp_rmem = 4096 32768 262142 
net.ipv4.tcp_ wmem = 4096 32768 262142 
net.core.netdev_ max_backlog = 8096 
net.core.rmem default = 262144 
net.core.wmem default = 262144 
net.core.rmem max = 2097152 
net.core.wmem max = 2097152 
net.ipv4.tcp_syncookies = 1 
net.ipv4.tcp_max_syn.backlog=1024 
\ /一 \ > A 
然后 执行 sysctl-p 命 令 ， 使 上 述 修改 生效 。 
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上 面 的 参数 意义 解释 如 下 : 


. fle-max: 这 个 参数 表示 进程 (比如 一 个 wotket 进 程 ) 可 以 同时 打 


开 的 最 大 句柄 数 ， 这 个 参数 直接 限制 最 大 并 发 连接 数 ， 需 根据 实际 情况 


配置 。 


` tcp_tw_teuse: 这 个 参数 设置 为 1， 表 示人 允许 将 IIME-WAIT 状 态 的 


socket 重 新 用 于 新 的 TCP 连 接 ， 这 对 于 服务 器 来 说 很 有 意义 ， 因 为 服务 


器 上 总 会 有 大 量 TIME-WAIT 状 态 的 连接 。 


.tcp_keepalive_time: 这 个 参数 表示 当 keepalive 启 用 时 ，TCP 发 送 
keepalive 消 息 的 频 度 。 默 认 是 2 小 时 ， 若 将 其 设置 得 小 一 些 ， 可 以 更 快 地 
青 理 无 效 的 3 连接 O 


. tcp_fin_timeout: 这 个 参数 表示 当 服 务 器 主动 关闭 连接 时 ，socket 


保持 在 FIN-WAIT-2 状 态 的 最 大 时 间 。 


` tcp_max_tw_buckets: 这 个 参数 表示 操作 系统 允许 TIME_WAIT 套 
接 字 数量 的 最 大 值 ， 如 果 超 过 这 个 数字 ，TIME_WAIT 套 接 字 将 立刻 被 
清除 并 打印 警告 信息 。 该 参数 默认 为 180000， 过 多 的 TIME_WAIT 套 接 


字 会 使 Web 服 务 器 变 慢 。 


.tcp_max_syn_backlog: 这 个 参数 表示 TCP 三 次 握手 建立 阶段 接收 
SYN 请 求 队列 的 最 大 长 度 ， 默 认为 1024， 将 其 设置 得 大 一 些 可 以 使 出 现 
Nginx 繁 忙 来 不 及 accept 新 连接 的 情况 时 ，Linux 不 至 于 丢失 客户 端 发 起 的 


连接 请 求 。 


.ip_local_port tanpge: 这 个 参数 定义 了 在 UDP 和 TCP 连 接 中 本 地 


(不 包括 连接 的 远 端 端口 的 取 值 范 围 。 


.netipv4.tcp_tmem: 这 个 参数 定义 了 TCP 接 收 缓存 (用 于 TCP 接 收 
滑动 窗口 ) 的 最 小 值 、 默 认 值 、 最 大 值 。 


.net'ipv4.tcp_wmem: 这 个 参数 定义 了 TCP 发 送 缓 存 (用 于 TCP 发 


送 滑动 窗口 ) 的 最 小 值 、 默 认 值 、 最 大 值 。 


netdev_max_backlog: 当 网 卡 接收 数据 包 的 速度 大 于 内 核 处 理 的 
速度 时 ， 会 有 一 个 队列 保存 这 些 数据 包 。 这 个 参数 表示 该 队列 的 最 大 
值 。 


. rmem_default: 这 个 参数 表示 内 核 套 接 字 接收 缓存 区 默认 的 大 


.wmem_default: 这 个 参数 表示 内 核 套 接 字 发 送 缓存 区 默认 的 大 


trmem_max: 这 个 参数 表示 内 核 套 接 字 接收 缓存 区 的 最 大 大 小 。 
.wmem_max: 这 个 参数 表示 内 核 套 接 字 发 送 缓存 区 的 最 大 大 小 。 


人 @@ i 意 ”滑动 窗口 的 大 小 与 套 楼 字 缓 存 区 会 在 一 定 程度 上 影响 并 
发 连接 的 数目 。 每 个 TCP 连 接 都 会 为 维护 TCP 滑 动 窗口 而 消耗 内 存 ， 这 
个 窗口 会 根据 服务 器 的 处 理 速 度 收缩 或 扩张 。 


参数 wmem_max 的 设置 ， 需 要 平衡 物理 内 存 的 总 大 小 、Nginx 并 发 处 
理 的 最 大 连接 数量 (由 nginx.conf 中 的 worker_processes 和 
worker_connections 参 数 决定 ) 而 确定 。 当 然 ， 如 果 仅 仅 为 了 提高 并 发 量 
使 服务 器 不 出 现 Out Of Memory 问 题 而 去 降低 滑动 窗口 大 小 ， 那 么 并 不 


合适 ， 因 为 滑动 窗口 过 小 会 影响 大 数据 量 的 传输 速度 。tmem_default、 
wmem_default、tmem_max、wmem_max 这 4 个 参数 的 设置 需要 根据 我 们 


的 业务 特性 以 及 实际 的 硬件 成 本 来 综合 考虑 。 
' tcp_syncookies: 该 参数 与 性 能 无 关 ， 用 于 解决 TCP 的 SYN 攻 击 。 
1.3.5 获取 Nginx 源 人 码 


可 以 在 Nginx 官 方 网 站 〈http:/nginx.org/en/download.html ) 获取 
Nginx 源 码 包 。 将 下 载 的 nginx-1.0.14.tar.gz 源 人 码 压 缩 包 放置 到 准备 好 的 
Nginx 源 代码 目录 中 ， 然 后 解压 。 例 如 ; 





tar -zxvf nginx-1.0.14.tar.gz 

















本 书 编写 时 的 Nginx 最 新 稳定 版 本 为 1.0.14〈 如 图 1-2 所 示 ) ， 本 书 
te a niin 

一 般 不 会 有 改动 〈 人 否则 大 量 第 三 方 模块 的 功能 就 无 法 保证 了 ) ， 即 使 
下 载 其 他 版 本 的 Nginx 源 码 包 也 不 会 影响 阅读 本 书 。 





CHANGES 
CHANGES-1.0 


人 GES- 
CHANGES-0.6 
CHANGES-0.5 


nginxX-1.1.17 pep 


nginxX-1.0.14 pgp 


ngsinxX-0.8 55 pep 
nginx-0.7.09 pep 





nginx: download 
Development version 

nginx/Windows-1.1.17 pgp 

Stable version 
nginx/Windows-1.0.14 pgp 

Legacy versions 
nginx/WindoWws-0 8 55 pgp 
nginx/Windows-0.7.69 pgp 
nginx-0.6.59 pgp 
nginx-0.5.38 pgp 


图 1-2 Nginx 的 不 同 版 本 


1.4 ”编译 安装 Nginx 


安装 Nginx 最 简单 的 方式 是 ， 进 入 nginx-1.0.14 目 录 后 执行 以 下 3 行 命 
./configure 


make 
make install 

















configure 命 令 做 了 大 量 的 “幕后 ”工作 ， 包 括 检测 操作 系统 内 核 和 已 
经 安装 的 软件 ， 参 数 的 解析 ， 中 间 目 录 的 生成 以 及 根据 各 种 参数 生成 一 
些 C 源 码 文 件 、Makefile 文 件 等 。 


make 命 令 根据 configure 命 令 生 成 的 Makefile 文 件 编译 Nginx 工 程 ， 并 
生成 目标 文件 、 最 终 的 二 进 制 文件 。 


make install 命 令 根 据 configure 执 行 时 的 参数 将 Nginx 部 上 车 到 指定 的 安 
装 目 录 ， 包 括 相 关 目 录 的 建立 和 二 进 制 文件 、 配 置 文件 的 复制 。 


1.5 ”configure 评 解 





可 以 看 出 ，configure 命 令 至 关 重 要 ， 下 文 将 详细 介绍 如 何 使 用 
configure 命 令 ， 并 分 析 configure 到 底 是 如 何 工 作 的 ， 从 中 我 们 也 可 以 看 


出 Nginx 的 一 些 设计 思 想 O 
1.5.1 ”configure 的 命令 参数 


使 用 help 命 令 可 以 查看 configure 包 含 的 参数 。 


./configure --help 





这 里 不 一 一 列 出 help 的 结果 ， 只 是 把 它 的 参数 分 为 了 四 大 类 型 ， 下 
面 将 会 详 述 各 类 型 下 所 有 参数 的 用 法 和 意义 。 


1. 路 径 相 关 的 参数 
表 1-2 列 出 了 Nginx 在 编译 期 、 运 行 期 中 与 路 径 相关 的 各 种 参数 。 


表 1-2 configure 支 持 的 路 径 相 关 参 数 


参数 名 称 


--prefix=PATH 


--Sbin-path=PATH 
--Conf-path=PATH 


--error-log-path=PATH 


--pid-path=PATH 


--lock-path=PATH 


--builddir=DIR 


--wWith-perl_modules_path=PATH 


--with-perl=PATH 


--http-log-path=PATH 


--http-client-body-temp-path=PATH 


--http-proxy-temp-path=PATH 


参数 名 称 
--http-fastcgi-temp-path=PATH 
--http-uwsgi-temp-path=PATH 
--http-scgi-temp-path=PATH 


Nginx 安装 部 署 后 的 根 目录 





可 执行 文件 的 放置 路 径 

error 日 志文 件 的 放置 路 径 。error 日 志 
用 于 定位 问题 ， 可 输出 多 种 级 别 (包括 
debug 调试 级 别 ) 的 日 志 。 它 的 配置 非常 
灵活 ， 可 以 在 nginx.conf 里 配置 为 不 同 请 
求 的 日 志 并 输出 到 不 同 的 log 文件 中 。 这 
里 是 默认 的 Nginx 核心 日 志 路 径 

pid 文件 的 存放 路 径 。 这 个 文件 里 仅 以 
ASC 人 码 存放 着 Nginx master 的 进程 ID， 
有 了 这 个 进程 DD， 在 使 用 命令 行 (例如 
nginx -s reload) 通过 读 取 master 进程 ID 
向 master 进程 发 送信 号 时 ， 才 能 对 运行 中 
的 Nginx 服务 产生 作用 

lock 文件 的 放置 路 径 

configure 执行 时 与 编译 期 间 产 生 的 临时 
文件 放置 的 目录 ,包括 产生 的 Makefile、 
C 源 文件 、 目 标 文 件 、 可 执行 文件 等 

perl module 放置 的 路 径 。 只 有 使 用 了 第 

: 方 的 perl module， 才 需要 配置 这 个 路 径 

perl binary 放置 的 路 径 。 如 果 配 置 的 Nginx 
会 执行 Perl 脚本 ， 那 么 就 必须 要 设置 此 路 径 

access 日 志 放 置 的 位 置 。 每 一 个 HTTP 
请 求 在 结束 时 都 会 记录 的 访问 日 志 

处 理 HTTP 请 求 时 如 果 请 求 的 包 体 需 要 
暂时 存放 到 临时 磁盘 文件 中 ， 则 把 这 样 的 
临时 文件 放置 到 该 路 径 下 

Nginx 作 为 HTTP 反 向 代理 服务 器 时 ， 
上 游 服务 器 产生 的 HTTP 包 体 在 需要 临时 
存放 到 磁盘 文件 时 ( 详 见 12.8 节 )， 这 样 
的 临时 文件 将 放 到 该 路 径 下 








Fastcgi 所 使 用 临时 文件 的 放置 目录 


UWSGI 所 使 用 临时 文件 的 放置 目录 


SCGI 所 使 用 临时 文件 的 放置 目录 





默认 值 
默认 为 /usr/local/nginx 目录 


<prefix>/sbin/nginx 


<prefix>/conf/nginx.conf 


<prefix>/logs/error.log 


<prefix>/logs/nginx.pid 


<prefix>/logs/nginx.lock 


<nginx source path>/objs 


无 
无 


<prefix>/logs/access.log 


<prefix>/client_body _ temp 


<prefix>/proxy_temp 


<prefix>/fastcgi_temp 


<prefix>/uwsg1 temp 


<prefix>/scgl temp 


注 


意 : 这 个 目标 的 设置 会 影响 其 他 参 
数 中 的 相对 目录 
置 了 --sbin-path=sbin/nginx， 那 么 
实际 上 可 执行 文件 会 被 放 到 /usr/ 


local/nginx/sbin/nginx 中 


例如 ， 如 果 设 


2. 编 译 相 关 的 参数 
表 1-3 列 出 了 编译 Nginx 时 与 编译 器 相关 的 参数 。 


表 1-3 configure 支 持 的 编译 相关 参数 


编译 参数 意 义 
--with-cc=PATH C 编译 咒 的 路 径 
--with-cpp=PATH C 预 编译 器 的 路 径 


如 果 和 希望 在 Nginx 编译 期 间 指定 加 入 一 些 编译 选项 ， 如 指定 宕 或 者 使 用 -I 加 入 某 些 
需要 包含 的 目录 ， 这 时 可 以 使 用 该 参数 达成 目的 


最 终 的 二 进 制 可 执行 文件 是 由 编译 后 生成 的 目标 文件 与 一 些 第 三 方 库 链接 生成 的 ， 
在 执行 链接 操作 时 可 能 会 需要 指定 链接 参数 ，--with-ld-opt 就 是 用 于 加 入 链接 时 的 参 
--With-ld-opt=OPTIONS | 数 。 例 如 ， 如 果 我 们 希望 将 某 个 库 链 接 到 Nginx 程序 中 ， 需 要 在 这 里 加 入 --with-ld- 
opt=llibraryName -LlibraryPath， 其 中 libraryName 是 目标 库 的 名 称 ，libraryPath 则 是 目 
标 库 所 在 的 路 径 
指定 CPU 处 理 器 架构 ， 只 能 从 以 下 取 值 中 选择 : pentium 、pentiumpro 、pentium3 、 
pentium4 、athlon、opteron、sparc32、sparc64、ppc64 


--With-cc-opt=OPTIONS 


--With-cpu-opt=CPU 


3. 依 赖 软件 的 相关 参数 


表 1-4~ 表 1-8 列 出 了 Nginx 依 赖 的 常用 软件 支持 的 参数 。 


表 1-4 PCRE 的 设置 参数 


PCRE 库 的 设置 参数 意 义 
如 果 确 认 Nginx 不 用 解析 正则 表达 式 ， 也 就 是 说 ，nginx.conf 配置 文件 中 不 会 出 


--Without-pcr 
RR 现 正则 表达 式 ， 那 么 可 以 使 用 这 个 参数 


--wWith-pcre 强制 使 用 PCRE 库 
--with-pcre=DIR 指定 PCRE 库 的 源码 位 置 ， 在 编译 Nginx 时 会 进入 该 目录 编译 PCRE 源码 
--with-pcre-opt=OPTIONS 编译 PCRE 源码 时 希望 加 入 的 编译 选项 


表 1-5 OpenSSL 的 设置 参数 


OpenSSL 库 的 设置 参数 意 义 
指定 OpenSSL 库 的 源码 位 置 ， 在 编译 Nginx 时 会 进入 该 目录 编译 OpenSSL 源码 


--with-openssl=DIR 注意 : 如 果 Web 服务 器 支持 HTTPS， 也 就 是 SSL 协议 ，Nginx 要 求 必须 使 
用 OpenSSL。 可 以 访问 http:/W/www.openssl.org/ 免费 下 载 
--with-openssl-opt=OPTIONS 编译 OpenSSL 源码 时 希望 加 入 的 编译 选项 


表 1-6 原子 库 的 设置 参数 


atomic (原子 ) 库 的 设置 参数 意 义 
强制 使 用 atomic 库 。atomic 库 是 CPU 架构 独立 的 一 种 原子 操作 的 实现 。 它 支持 
--with-libatomic 以 下 体系 架构 : x86 (包括 i386 和 x86_64 )、PPC64、Sparc64 (v9 或 更 高 版 本 ) 或 
者 安装 了 GCC 4.1.0 及 更 高 版 本 的 架构 。14.3 节 介绍 了 原子 操作 在 Nginx 中 的 实现 
--with-libatomic=DIR atomic 库 所 在 的 位 置 


表 1-7 散 列 函数 库 的 设置 参数 


散 列 函数 库 的 设置 参数 意 义 
指定 MD5 库 的 源码 位 置 ， 在 编译 Nginx 时 会 进入 该 目录 编译 MD5 源码 
--with-MD5=DIR 注意 : Nginx 源码 中 已 经 有 了 MD5 算法 的 实现 ， 如 果 没 有 特殊 需求 ， 那 么 完 
全 可 以 使 用 Nginx 自身 实现 的 MD5 算法 
--with-MD5-opt=OPTIONS 编译 MD5 源码 时 希望 加 入 的 编译 选项 
---With-MD5-asm 使 用 MD5 的 汇编 源码 
指定 SHA1 库 的 源码 位 置 ， 在 编译 Nginx 时 会 进入 该 日 当 缚 水 : SHA1 源码 
--with-SHA1=DIR 注意 : OpenSSL 中 已 经 有 了 SHA1 算法 的 实现 。 如 果 已 经 安装 了 OpenSSL， 
那么 完全 可 以 使 用 OpenSSL 实现 的 SHA1 算法 
--with-SHA1-opt=OPTIONS 编译 SHA1 源码 时 希望 加 入 的 编译 选项 
--with-SHA1-asm 使 用 SHA1 的 汇编 源码 


表 1-8 zlib 库 的 设置 参数 


zlib 库 的 设置 参数 意 义 

指定 zlib 库 的 源码 位 置 ， 在 编译 Nginx 时 会 进入 该 目录 编译 zlib 源码 。 如 果 使 
用 了 gzip 压缩 功能 ， 就 需要 zlib 库 的 支持 
--with-zlib-opt=OPTIONS 编译 zlib 源码 时 希望 加 入 的 编译 选项 

指定 对 特定 的 CPU 使 用 zlib 库 的 汇编 优化 功能 ， 目 前 仅 支 持 两 种 架构 : pentium 
和 pentiumpro 


--With-zlib=DIR 


--With-zlib-asm=CPU 


4. 模 块 相关 的 参数 


除了 少量 核心 代码 外 ，Nginx 完 全 是 由 各 种 功能 模块 组 成 的 。 


模块 会 根据 配置 参数 决定 自己 的 行为 ， 因 此 ， 正 确 地 使 用 各 个 模块 非常 
关键 。 在 configure 的 参数 中 ， 我 们 把 它们 分 为 五 大 类 。 


“ 事件 模块 。 

` 默认 即 编 译 进入 Nginx 的 HTTP 模 块 。 

" 默认 不 会 编译 进入 Nginx 的 HTTP 模 块 。 

- 邮件 代理 服务 器 相关 的 mail 模 块 。 

" 其 他 模块 。 

(1) 事件 模块 
表 1-9 中 列 出 了 Nginx 可 以 选择 哪些 事件 模块 编译 到 产品 中 。 


表 1-9 ”configure 支 持 的 事件 模块 参数 


编译 参数 


--with-rtsig module 


--With-select module 


--Without-select module 


--with-poll module 


--Without-poll module 


--With-alo_ module 


意 义 

使 用 rtsig module 处 理事 件 驱动 

默认 情况 下 ，Nginx 是 不 安装 rtsig module 的 ， 即 不 会 把 rtsig module 编译 进 最 终 的 
Nginx 二 进 制 程序 中 

使 用 select module 处 理事 件 驱 动 

select 是 Linux 提供 的 一 种 多 路 复 用 机 制 ， 在 epoll 调用 没有 诞生 前 ， 例 如 在 Linux 
2.4 及 其 之 前 的 内 核 中 ，select 用 于 支持 服务 器 提供 高 并 发 连接 

默认 情况 下 ，Nginx 是 不 安装 select module 的 ， 但 如 果 没 有 找到 其 他 更 好 的 事件 模 
块 ， 该 模块 将 会 被 安装 

不 安装 select module 

使 用 poll module 处 理事 件 驱 动 

poll 的 性 能 与 select 类 似 ， 在 大 量 并 发 连接 下 性 能 都 远 不 如 epoll。 默 认 情 况 下 ， 
Neginx 是 不 安装 poll module 的 

不 安装 poll module 

使 用 AIO 方式 处 理事 件 驱 动 

注意 : 这 里 的 aio module 只 能 与 FreeBSD 操作 系统 上 的 kqueue 事件 处 理 机 制 合作 ， 
Linux 上 无 法 使 用 


默认 情况 下 是 不 安装 aio module 的 


(2) 默认 即 编译 进入 Nginx 的 HITP 模 块 


表 1-10 列 出 了 默认 就 会 编译 进 Nginx 的 核心 HTTP 模 块 ， 以 及 如 何 把 
这 些 HTTP 模 块 从 产品 中 去 除 。 


表 1-10 


configute 中 默认 编译 到 Nginx 中 的 HTTP 模 块 参数 


默认 安装 的 HTTP 模块 


--wWithout-http_charset module 


--without-http_gzip_module 


--without-http_ssi _ module 


--without-http_userid_ module 


--Without-http_access_ module 


--without-http_auth basic module 


--Without-http_autoindex module 


--without-http_geo_module 


意 义 

不 安装 http charset module。 这 个 模块 可 以 将 服务 器 发 出 的 HTTP 响应 
重 编码 

不 安装 http gzip module-。 在 服务 器 发 出 的 HITP 响应 包 中 ， 这 个 模块 
可 以 按照 配置 文件 指定 的 content-type 对 特定 大 小 的 HTTP 响应 包 体 执 行 
gzip 压缩 

不 安装 http ssi module。 该 模块 可 以 在 向 用 户 返 回 的 HTTP 响应 包 体 中 
加 入 特定 的 内 容 ， 如 HTML 文件 中 固定 的 页 头 和 页 尾 

不 安装 http userid module。 这 个 模块 可 以 通过 HTTP 请 求 头 部 信息 里 的 

- 些 字段 认证 用 户 信 息 ， 以 确定 请 求 是 否 合法 

不 安装 http access module。 这 个 模块 可 以 根据 全 地址 限制 能 够 访问 服 
务 融 的 客户 端 

不 安装 http auth basic module。 这 个 模块 可 以 提供 最 简单 的 用 户 名 / 密 
码 认 证 

不 安装 http autoindex module。 该 模块 提供 简单 的 目录 浏览 功能 

不 安装 http geo module。 这 个 模块 可 以 定义 一 些 变量 ， 这 些 变量 的 值 将 
与 客户 端 IP 地 址 关联 ， 这 样 Nginx 针对 不 同 的 地 区 的 客户 端 (根据 IP 
地 址 判断 ) 返回 不 一 样 的 结果 ， 例 如 不 同 地 区 显示 不 同 语言 的 网 页 


默认 安装 的 HTTP 模块 


--wWithout-http map module 


--wWithout-http split clients_module 


--Without-http_referer module 


--Without-http_ rewrite module 


--wWithout-http_proxy_ module 
--Without-http_fastcgi module 
--Without-http_uUwsgi module 


--wWithout-http scgi_ module 


--without-http_memcached module 


--wWithout-http_ limit zone module 


--Without-http_limit req_module 


--wWithout-http_ empty_gif module 


--Without-http_browser module 


--wWithout-http_upstream_ip_hash module 





( 续 ) 


意 义 

不 安装 http map module。 这 个 模块 可 以 建立 一 个 key/value 映射 表 ， 不 
同 的 key 得 到 相应 的 value， 这样 可 以 针对 不 同 的 URL 做 特殊 人 处理 。 例 
如 ， 返 回 302 重 定向 响应 时 ， 可 以 期 望 URL 不 同时 返回 的 Location 字段 
也 不 一 样 

不 安装 http split client module。 该 模块 会 根据 客户 端的 信息 ， 例 如 卫 
地 址 、header 头 、cookie 等 ， 来 区 分 处 理 

不 安装 http referer module。 该 模块 可 以 根据 请 求 中 的 referer 字段 来 拒 
绝 请 求 

不 安装 http rewrite module。 该 模块 提供 HTTP 请 求 在 Nginx 服务 内 部 
的 重 定 向 功能 ,依赖 PCRE 库 

不 安装 http proxy module。 该 模块 提供 基本 的 HTTP 反 向 代理 功能 

不 安装 http fastcgi module。 该 模块 提供 FastCGI 功能 

不 安装 http uwsgi module。 该 模块 提供 uWSGI 功能 

不 安装 http scgi module。 该 模块 提供 SCGI 功能 

不 安装 http memcached module- 该 模块 可 以 使 得 Nginx 直接 由 上 游 的 
memcached 服务 读 取 数据 ， 并 简单 地 适 配 成 HTTP 响应 返回 给 客户 端 

不 安装 http limit zone module。 该 模块 针对 某 个 IP 地 址 限制 并 发 连接 
数 。 例 如 ,使 Nginx 对 一 个 卫 地 址 仅 允许 一 个 连接 

不 安装 http limit req module。 该 模块 针对 某 个 IP 地 址 限制 并 发 请 求 数 

不 安装 http empty gif module。 该 模块 可 以 使 得 Nginx 在 收 到 无 效 请 求 
时 ， 立 刻 返 回 内 存 中 的 1x 1 像素 的 GIF 图 片 : 这 种 好 处 在 于 ， 对 于 明显 
的 无 效 请 求 不 会 去 试图 浪费 服务 器 资源 

不 安装 http browser module。 该 模块 会 根据 HTTP 请 求 中 的 user-agent 
字段 (该 字段 通常 由 浏览 器 填写) 来 识别 浏览 器 

不 安装 http upstream ip hash module。 该 模块 提供 当 Nginx 与 后 端 server 
建立 连接 时 ,会 根据 IP 做 散 列 运算 来 决定 与 后 端 哪 台 server 通信 ， 这 样 
可 以 实现 负载 均衡 


(3) 默认 不 会 编译 进入 Nginx 的 HTTP 模 块 


表 1-11 列 出 了 默认 不 会 编译 至 Nginx 中 的 HTTP 模 块 以 及 把 它们 加 入 


产品 中 的 方法 。 


表 1-11 


configute 中 默认 不 会 编译 到 Nginx 中 的 HITP 模 块 参 数 


可 选 的 HTTP 模块 


--with-http_ssl module 


--with-http_realip_module 


--with-http_addition module 


意 义 


安装 http ssl module。 该 模块 使 Nginx 支持 SSL 协议 ,提供 HTTPS 服务 
注意 : 该 模块 的 安装 依赖 于 OpenSSL 开源 软件 ， 即 首先 应 确保 已 经 在 之 前 


的 参数 中 配置 了 OpenSSL 


安装 http realip module 





该 模块 可 以 从 客户 端 请 求 里 的 header 信息 (如 


X-Real-IP 或 者 X-Forwarded-For) 中 获取 直 正 的 客户 端 卫 地 址 


安装 http addtion module 
尾部 增加 内 容 


该 模块 可 以 在 返回 客户 端的 HITP 包 体 头 部 或 者 


可 选 的 HTTP 模块 


--With-http Xslt module 


--With-http image _filter module 


—with-http_geoip module 


-—with-http_sub_ module 


—With-http_dav_module 


--wWith-http_flv_ module 


--wWith-http_ mp4 module 


-=-wWith-http_gzip_static_module 


—with-http_random index_module 


-with-http_secure link module 


-with-http_degradation module 


--with-http_stub_status_module 


--With-google perftools module 


( 续 ) 
意 义 

安装 http xslt module。 这 个 模块 可 以 使 XML 格式 的 数据 在 发 给 客户 端 前 加 
入 XSL 泻 染 

注意 ; 这 个 模块 依赖 于 libxml2 和 libxslt 库 ， 安 装 它 前 首先 确保 上 上 述 两 个 
软件 已 经 安装 

安装 http image_filter module。 这 个 模块 将 符合 配置 的 图 片 实时 压缩 为 指定 
大 小 (width*height) 的 缩 略 图 再 发 送 给 用 户 ， 目 前 支持 JPEG ,PNG ,GIF 格式 

注意 : 这 个 模块 依赖 于 开源 的 libgd 库 ， 在 安装 前 确保 操作 系统 已 经 安装 了 
libgd 

安装 http geoip module。 该 模块 可 以 依据 MaxMind GeolP 的 IP 地 址 数据 库 
对 客户 端的 IP 地 址 得 到 实际 的 地 理 位 置信 息 

注意 : 该 库 依赖 于 MaxMind GeolP 的 库 文件 ， 可 访问 http://geolite.maxmind. 
com/download/geoip/database/GeoLiteCity.dat.gz 获取 

安装 http sub module。 该 模块 可 以 在 Nginx 返回 客户 端的 HTTP 响应 包 中 
将 指定 的 字符 串 替 换 为 日 已 需要 的 字符 串 

例如 . 在 HITML 的 返回 中 、 将 Shead> 替换 为 </head><script language="javascript" 
src="$script"></script> 

安装 http dav module。 这 个 模块 可 以 让 Nginx 支持 Webdav 标准 ， 
Webdav 协议 中 的 PUT、DELETE 、COPY 、MOVE 、MKCOL 等 请 求 

安装 http flv module- 这 个 模块 可 以 在 向 客户 端 返 回响 应 时 ,对 FLV 格式 
的 视频 文件 在 header 头 做 一 些 处 理 ， 使 得 客户 端 可 以 观看 、 拖 动 FLV 视频 

安装 http mp4 module。 该 模块 使 客户 端 可 以 观看 、 拖 动 MP4 视频 

安装 http gzip static module。 如 果 采 用 gzip 模块 把 一 些 文档 进行 gzip 格式 
压缩 后 再 返回 给 客户 端 ， 那么 对 同一 个 文件 每 次 都 会 重新 压缩 ， 这 是 比较 消 
耗 服 务 虽 CPU 资源 的 。gzip static 模块 可 以 在 做 gzip 压缩 前 ， 先 查看 相同 位 
置 是 否 有 已 经 做 过 gzip 压缩 的 .gz 文件 ， 如 果 有 ， 就 直接 返回 。 这样 就 可 以 
预先 在 服务 器 上 做 好 文档 的 压缩 ， 给 CPU 减负 

安装 http random index module。 该 模块 在 客户 端 访问 某 个 目录 时 ， 随 机 返 
回 该 目录 下 的 任意 文件 

安装 http secure link module。 该 模块 提供 一 种 验证 请 求 是 否 有 效 的 机 制 。 
例如 ， 它 会 验证 URL 中 需要 加 入 的 token 参数 是 否 属 于 特定 客户 端 发 来 的 ， 
以 及 检查 时 间 蕉 是 否 过 期 

安装 http degradation module。 该 模块 针对 一 些 特殊 的 系统 调用 (如 sbrk) 
做 一 些 优化 ， 如 直接 返回 HTTP 响应 码 为 204 或 者 444。 目 前 不 支持 Linux 
系统 

安装 http stub status module。 该 模块 可 以 让 运行 中 的 Nginx 提供 性 能 统计 
页 面 ， 获 取 相 关 的 并 发 连接 、 请 求 的 信息 (14.2.1 节 中 简单 介绍 了 该 模块 的 
原理 ) 

安装 google perftools module。 该 模块 提供 Google 的 性 能 测试 工具 


如 支持 


(4) 邮件 代理 服务 器 相关 的 mail 模 块 


表 1-12 列 出 了 把 邮件 模块 编译 到 产品 中 的 参数 。 


1 


可 选 的 mail 模块 


--With-mail 


--With-mail ssl module 


--without-mail pop3_module 


--Without-mail_ imap_ module 


--without-mail smtp module 


其 他 参数 


configure 还 接收 一 


--With-debusg 


--add-module=PATH 


--without-http 
--Without-http-cache 
--with-file-aio 


--With-1pv6 
--USeI=USER 


--group=GROUP 


De 


表 1-12 ”configure 提 供 的 邮件 模块 参数 


did 使 Nginx 可 以 反 向 代理 IMAP、POP3、SMTP 


等 协议 。 该 模块 默认 不 安装 
安装 mail ssl module。 该 模块 可 以 使 IMAP、POP3、SMTP 等 
TLS 协议 之 上 使 用 。 该 模块 默认 不 安装 并 依赖 于 OpenSSL 库 


协议 基于 SSL/ 


不 安装 mail pop3 module。 在 使 用 --with-mail 参数 后 ，pop3 module 是 默认 安 
装 的 ， 以 使 Nginx 支持 POP3 协议 
不 安装 mail imap module。 在 使 用 --with-mail 参数 后 ，imap module 是 默认 安 


装 的 ， 以 使 Nginx 支持 IMAP 
不 安 妆 


装 的 ， 


月 . 鲜 


志 mail smtp module。 在 使 用 --with-mail 参数 后 ，smtp module 是 默认 安 


以 使 Nginx 支持 SMTP 


举 其 他 参数 ， 表 1-13 中 列 出 了 相关 参数 的 说 明 。 


表 1-13 configure 提 供 的 其 他 参数 
意 义 

将 Nginx 需要 打印 debug 调试 级 别 日 志 的 代码 编译 进 Nginx。 这 样 可 以 在 Nginx 运行 
时 通过 修改 配置 文件 来 使 其 打印 调试 日 志 ， 这 对 于 研究 、 2 Nginx 问题 非常 有 帮助 

当 在 Nginx 里 加 入 第 三 方 模块 时 ， 通 过 这 个 参数 指定 第 三 方 模块 的 路 径 。 这 个 参数 将 
在 下 文 如 何 开 发 HTTP 模块 时 使 用 到 

标 用 HTTP 服务 器 

禁用 HTTP 服务 器 里 的 缓存 Cache 特性 

启用 文件 的 异步 IO 功能 来 处 理 磁盘 文件 ， 

使 Nginx 支持 IPV6 

指定 Nginx worker 进程 运行 时 所 属 的 用 户 

注意 : 不 要 将 启动 worker 进程 的 用 户 设 
要 具备 停止 / 启动 worker 进程 的 能 力 
了 时 所 属 的 组 


这 需要 Linux 内 核 支持 原生 的 异步 IO 


为 root， 在 worker 进程 出 问题 时 master 进程 


指定 Nginx worker 进程 运 和 


configure 执 行 流程 


我 们 看 到 configure 命 令 支 持 非 常 多 的 参数 ， 读 者 可 能 会 好 奇 它 在 执 
行 时 到 底 做 了 哪些 事情 ， 本 节 将 通过 解析 configure 源 码 来 对 它 有 一 个 感 
性 的 认识 。configure 由 Shell 脚 本 编写， 中间 会 调用 <nginx-source>/auto/ 
目录 下 的 脚本 。 这 里 将 只 对 configure 脚 本 本 身 做 分 析 ， 对 于 它 所 调用 的 
auto 目 录 下 的 其 他 工具 脚本 则 只 做 功能 性 的 说 明 。 


configure 脚 本 的 内 容 如 下 : 





#!1/bin/sh 

# Copyright (C) Igor Sysoev 
# Copyright (C) Nginx, Inc. 
#aUuto/options 脚 本 处 理 


configure 命 令 的 参数 。 例 如 ， 如 果 参 数 是 


--help， 那 么 显示 支持 的 所 有 参数 格式 。 


options 脚 本 会 定义 后 续 工 作 将 要 用 到 的 变量 ， 然 后 根据 本 次 参数 以 及 默认 值 设置 这 些 变量 


，auto/options 
#auto/init 脚 本 初始 化 后 续 将 产生 的 文件 路 径 。 例 如 ， 


Makefile.、 


ngx_modules.c 等 文件 默认 情况 下 将 会 在 


<nginx-source>/objs/ 
. auto/init 
#auto/sources 脚 本 将 分 析 


Nginx 的 源码 结构 ， 这 样 才能 构造 后 续 的 


Makefile 文 件 


. auto/sources 
# 编 译 过 程 中 所 有 目标 文件 生成 的 路 径 由 一 


bujilddir=DIR 参 数 指定 ， 默 认 情 况 下 为 


<nginx-source>/objs， 此 时 这 个 目录 将 会 被 创建 


test -d $NGX_OBJS || mkdir $NGX_0BJS 
# 开 始 准备 建立 


ngx_auto_headers.h、 


autoconf .err 等 必要 的 编译 文件 


echo > $NGX_AUTO_HEADERS_H 
echo > $NGX_AUTOCONF_ERR 
# 向 


洲 


objs/ngx_auto_config.h 写 入 命令 行 带 的 参数 


echo "#define NGX_ CONFIGURE \"$NGX_ CONFIGURE\"" > $NGX_AUTO_CONFIG H 
# 判 断 


DEBUG 标 志 ， 如 果 有 ， 那 么 在 


objs/ngx_auto_config.h 文 件 中 写 入 


DEBUG 宏 


if [ $NGX_DEBUG = YES ]; then 
have=NGX_DEBUG . auto/have 

fi 

# 现 在 开始 检查 操作 系统 参数 是 否 支 持 后 续 编译 


if test -z "$NGX_ PLATFORM"; then 
echo "checking for OS" 
NGX_SYSTEM= uname -s 2>/dev/null. 
NGX_RELEASE= uname -r 2>/dev/null. 
NGX_MACHINE= “uname -m 2>/dev/null. 
# 屏 幕 上 输出 


0S 名 称 、 内 核 版 本 、 


32 位 


/64 位 内 核 


echo " + $NGX_SYSTEM $NGX_RELEASE $NGX_MACHINE" 
NGX_PLATFORM="$NGX_SYSTEM: $NGX_RELEASE: $NGX_MACHINE",; 


case "$NGX_SYSTEM" in 
MINGW32_*) 
NGX_PLATFORM=win32 
;7 
esac 
else 
echo "building for $NGX_PLATFORM" 
NGX_SYSTEM=$NGX_PLATFORM 
fi 
# 检 查 并 设置 编译 器 ， 如 


GCC 是 否 安 装 、 


GCC 版 本 是 否 支持 后 续 编译 


nginx 
auto/cc/conf 
# 对 非 


Windows 操 作 系统 定义 一 些 必 要 的 头 文件 ， 并 检查 其 是 否 存在 ， 以 此 决定 


configure 后 续 步 骤 是 和 否 可 以 成 功 


[1] 

if [ "$NGX_PLATFORM" != win32 ]; then 
auto/headers 

fi 


# 对 于 当前 操作 系统 ， 定 义 一 些 特定 的 操作 系统 相关 的 方法 并 检查 当前 环境 是 否 支持 。 例 如 ， 对 于 


Linux， 在 这 里 使 用 


sched_setaffinity 设 置 进程 优先 级 ， 使 用 


Linux 特 有 的 


Sendfi]le 系 统 调用 来 加 速 向 网 络 中 发 送 文 件 块 


. auto/os/conf 
#4 定义 类 


UNIX 操作 系统 中 通用 的 头 文 件 和 系统 调用 等 ， 并 检查 当前 环境 是 否 支持 


if [ "$NGX_PLATFORM" != win32 ]; then 
. aUuto/unNix 

fi 

# 最 核心 的 构造 运行 期 


modules 的 脚本 。 它 将 会 生成 


ngx_modules.c 文 件 ， 这 个 文件 会 被 编译 进 


Nginx 中 ， 其 中 它 所 做 的 唯一 的 事情 就 是 定义 了 


ngx_modules 数 组 。 


ngx_modules 指 明 


Nginx 运 行 期 间 有 哪些 模块 会 参与 到 请 求 的 处 理 中 ， 包 括 


HTTP 请 求 可 能 会 使 用 哪些 模块 处 理 ， 因 此 ， 它 对 数组 元 素 的 顺序 非常 敏感 ， 也 就 是 说 ， 绝 大 部 分 模块 在 


ngx_modules 数 组 中 的 顺序 其 实 是 国定 的 。 例 如 ， 一 个 请 求 必 须 先 执行 


ngx_http_gzip_filter_module 模 块 重新 修改 





HTTP 响 应 中 的 头 部 后 ， 才 能 使 用 


ngx_http_header_filter 模 块 按照 


headers_in 结 构 体 里 的 成 员 构造 出 以 


TCP 流 形式 发 送 给 客户 端的 


HTTP 响 应 头 部 。 注 意 ， 我 们 在 


--add-module= 参 数 里 加 入 的 第 三 方 模块 也 在 此 步骤 写 入 到 


ngx_modules.c 文 件 中 了 


. auto/modules 
##COnf 脚 本 用 来 检查 


Nginx 在 链接 期 间 需 要 链接 的 第 三 方 静态 库 、 动 态 库 或 者 目标 文件 是 否 存 在 


. auto/lib/conf 


# 处 理 


Nginx 安 装 后 的 路 径 


case ".$NGX PREFIX" in 


.) 
NGX_PREFIX=${NGX_PREFIX: -/usr/local/nginx} 
have=NGX_PREFIX value="\"$NGX_ PREFIX/\"" . auto/define 
7 7 
.!) 
NGX_PREFIX= 
7 7/ 
*) 
have=NGX_PREFIX value="\"$NGX PREFIX/\"" . auto/define 
7 7 
esac 
# 处 理 
Nginx 安 装 后 
Conf 文 件 的 路 径 
if [ ".$NGX_CONF_PREFIX" != "." ]; then 
have=NGX_CONF_PREFIX value="\"$NGX CONF_PREFIX/\"" . auto/define 
fi 
# 处 理 


pid、 


lock 等 其 他 文件 的 路 径 可 参见 


configure 参 数 中 路 径 类 选项 的 说 明 


have=NGX_SBIN_PATH value="\"$NGX_ SBIN PATH\"" . auto/define 




















have=NGX_CONF_PATH value="\"$NGX_ CONF_PATH\"" . auto/define 

have=NGX_PID_PATH value="\"$NGX_PID_ PATH\"" . auto/define 

have=NGX_LOCK_PATH value="\"$NGX LOCK_PATH\"" . auto/define 

have=NGX_ERROR_LOG _ PATH value="\"$NGX ERROR LOG PATH\"" . auto/define 
have=NGX_HTTP_LOG_ PATH value="\"$NGX_HTTP_LOG PATH\"" . auto/define 
have=NGX_HTTP_CLIENT_TEMP_PATH value="\"$NGX_ HTTP_CLIENT_ TEMP_PATH\"" . auto/define 
have=NGX_HTTP_PROXY_TEMP_PATH value="\"$NGX_ HTTP_PROXY_TEMP_PATH\"" . auto/define 
have=NGX_HTTP_FASTCGI_TEMP_PATH value="\"$NGX_ HTTP_FASTCGI_TEMP_PATH\"" . auto/defir 
have=NGX_HTTP_UWSGI_TEMP_PATH value="\"$NGX HTTP_UWSGI_TEMP_PATH\"" . auto/define 
have=NGX_HTTP_SCGI_TEMP_PATH value="\"$NGX_ HTTP_SCGI_TEMP_PATH\"" . auto/define 








# 创 建 编译 时 使 用 的 


Objs/Makefile 文 件 


. auto/make 
# 为 


objs/Makefile 加 入 需要 连接 的 第 三 方 静态 库 、 动 态 库 或 者 目标 文件 


auto/lib/make 
# 为 


objs/Makefile 加 入 
Instal] 功 能 ， 当 执行 


make install 时 将 编译 生成 的 必要 文件 复制 到 安装 路 径 ， 建 立 必要 的 目录 


, auto/install 
# 在 
ngx_auto_config.h 文 件 中 加 入 


NGX_SUPPRESS_WARN 宏 、 


NGX_SMP 安 


auto/stubs 


# 在 


ngx_auto_config.h 文 件 中 指定 


NGX_USER 和 


NGX_GROUP 宏 ， 如 果 执 行 


configure 时 没有 参数 指定 ， 默 认 两 者 名 为 


nobody (也 就 是 默认 以 


nobody 用 户 运 行进 程 ) 


have=NGX_USER value="\"$NGX_USER\"" . auto/define 
have=NGX_GROUP value="\"$NGX _ GROUP\"" . auto/define 
# 显 示 


configure 执 行 的 结果 ， 如 果 失 败 ， 则 给 出 原因 


，auto/Ssummary 





( 注 : 在 configure 脚 本 里 检查 菜 个 特性 是 否 存 在 时 ,会 生成 一 个 最 简单 的 只 包含 main 肠 : 


1.5.3 ”configure 生 成 的 文件 


当 configure 执 行 成 功 时 会 生成 objs 目 录 ， 并 在 该 目录 下 产生 以 下 目录 和 文件 : 





--ngx_auto_headers .h 
--autoconf .err 
--ngx_auto_config.h 
--ngx_modules.c 
--Src 


而 :3 -而 辣 ，， 关 

WW ict 
号 
口 
[= 本 
大 
饭 
CD 
a 





|---Makefile 





上 述 目录 和 文件 介绍 如 下 。 

















1) src 目 录用 于 存放 编译 时 产生 的 目标 文件 。 











2) Makefile 文 件 用 于 绢 














i 译 Nginx 工 程 以 及 在 加 入 install 参 数 后 安装 Nginx。 





3) autoconf.err 保 存 configure 执 行 过 程 中 产生 的 结果 。 





> 


4) ngx_auto_headers.h 和 ngx_auto_config.h 保 存 了 一 些 宏 ， 这 两 个 头 文件 会 被 src/coremngx 





5) ngx_modules.c 是 一 个 关键 文件 ， 我 们 需要 看 看 它 的 内 部 结构 。 一 个 默认 配置 下 生成 昌 


#include <ngx_config.h> 
#include <ngx_core.h>:… 


ngx_module _t *ngx_modules[] = 


&ngx_core_module, 
&ngx_errlog _ module, 
&ngx_conf_module, 
&ngx_events_module, 
&ngx_event_core module, 
&ngx_epoll] module, 
&ngx_http_module, 
&ngx_http_core module, 
&ngx_http_log_module, 





{ 


&ngx_http_upstream module, 


&ngx_http_static module, 


&ngx_http_autoindex_module, 


&ngx_http_index_module, 


&ngx_http_auth_ basic module, 


&ngx_http_access_ module, 


&ngx_http_limit zone module, 
&ngx_http_limit_req_module, 


&ngx_http_geo_module, 
&ngx_http_map_module, 





&ngx_http_split_clients module, 


&ngx_http_referer_module, 
&ngx_http_rewrite module, 
&ngx_http_proxy_module, 
&ngx_http_fastcgi module, 
&ngx_http_uwsgi module, 
&ngx_http_scgi module, 


&ngx_http_memcached_module, 
&ngx_http_empty_gif_module, 


&ngx_http_browser_module, 
&ngx_http_upstream_ ip_hash_ module, 
&ngx_http_write_ filter_module, 
&ngx_http_header_filter_module, 
&ngx_http_chunked_filter_module, 
&ngx_http_range_header_filter_module, 
&ngx_http_gzip_filter_module, 
&ngx_http_postpone_filter_module, 
&ngx_http_ssi filter_module, 
&ngx_http_charset_filter_module, 
&ngx_http_userid filter_module, 
&ngx_http_headers_filter_module, 
&ngx_http_copy_filter_module, 
&ngx_http_range_body_filter_module, 
&ngx_http_not_modified_ filter_module, 
NULL 


















































ngx_modules.c 文 件 就 是 用 来 定义 ngx_modules 数 组 的 。 


ngx_modules 是 非常 关键 的 数组 ， 它 指明 了 每 个 模块 在 Nginx 中 的 优先 级 ， 当 一 个 请 求 同 | 








因此 ，ngx_modules 中 模块 的 先后 顺序 非常 重要 ， 不 正确 的 顺序 会 导致 Nginx 无 法 工作 ，: 





可 以 看 出 ， 在 安装 过 程 中 ，configure 做 了 大 量 的 幕后 工作 ， 我 们 需要 关注 在 这 个 过 程 中 ] 














configure 除 了 生成 Makefile 外 ， 还 生成 了 ngx_modules.c 文 件 ， 它 决定 了 运行 时 所 有 模块 上 





[1] 
在 configute 脚 本 里 检查 某 个 特性 是 否 存在 时 ， 会 生成 一 个 最 简单 的 只 包含 main 函 数 的 C 程 序 ， 


1.6 Nginx 的 命令 行 控制 


在 Linux 中 ， 需 要 使 用 命令 行 来 控制 Nginx 服 务 占 的 局 动 与 停止 、 重 
载 配置 文件 、 回 滚 日 志文 件 、 平 滑 升 级 等 行为 。 默 认 情 况 下 ，Nginx 被 
安装 在 目录 /usr/local/nginx/ 中 ， 其 二 进 制 文件 路 径 
为 /asrlocalnginc/sbin/nginx， 配 置 文件 路 径 
为 /usr/local/nginx/conf/nginx.conf。 当 然 ， 在 configure 执 行 时 是 可 以 指定 
把 它们 安装 在 不 同 目录 的 。 为 了 简单 起 见 ， 本 节 只 说 明 默 认 安 装 情况 下 
的 命令 行 的 使 用 情况 ， 如 果 读 者 安装 的 目录 发 生 了 变化 ， 那 么 苦 换 一 下 
即 可 。 


(1) 默认 方式 局 动 


直接 执行 Nginx 二 进 制程 序 。 例 如 : 





/usr/local/nginx/sbin/nginx 





这 时 ， 会 读 取 默 认 路 径 下 的 配置 文 


件 : /usr/local/nginx/conf/nginx.conf。 


实际 上 ， 在 没有 显 式 指定 nginx.conf 配 置 文件 路 径 时 ， 将 打开 在 
configure 命 令 执行 时 使 用 --conf-path=PATH 指 定 的 nginx.conf 文 件 〈 人 参见 
1.5T 5 


(2) 男 行 指定 配置 文件 的 局 动 方式 


使 用 -c 参 数 指定 配置 文件 。 例 如 : 





/usr/local/nginx/sbin/nginx -c /tmp/nginx.conf 





这 时 ， 会 读 取 -c 参 数 后 指定 的 nginx.conf 配 置 文件 来 启动 Nginx。 





(3) 男 行 指定 安装 目录 的 启动 方式 





使 用 -p 参 数 指定 Nginx 的 安装 目录 。 例 如 : 





/usr/local/nginx/sbin/nginx -p /usr/local/nginx/ 





(4) 男 行 指定 全 局 配置 项 的 启动 方式 


可 以 通过 -g 参 数 临 时 指定 一 些 全 局 配置 项 ， 以 使 新 的 配置 项 生效 。 
例如 : 





/usr/local/nginx/sbin/nginx -g "pid /var/nginx/test.pid;" 








上 面 这 行 命令 意味 着 会 把 pid 文 件 写 到 /var/nginx/test.pid 中 。 


-g 参 数 的 约束 条 件 是 指定 的 配置 项 不 能 与 默认 路 径 下 的 nginx.conf 中 
的 配置 项 相 冲 突 ， 盏 则 无 法 启动 。 束 像 上 例 那 样 ， 类 似 这 样 的 配置 项 : 
pid logs/nginx.pid， 是 不 能 存在 于 默认 的 nginx.conf 中 的 。 





男 一 个 约束 条 件 是 ， 以 -g 方 式 局 动 的 Nginx 服 务 执行 其 他 命令 行 
时 ， 需 要 把 -g 参 数 也 带 上 ， 人 否则 可 能 出 现 配 置 项 不 匹配 的 情形 。 例 如 ， 
如 果 要 停止 Nginx 服 务 ， 那 么 需要 执行 下 面 代码 : 











/usr/local/nginx/sbin/nginx -g "pid /var/nginx/test.pid;" -s stop 





如 果 不 带 上 -g"pid/var/nginx/test.pid;"， 那 么 找 不 到 pid 文 件 ， 也 会 出 
现 无 法 停止 服务 的 情况 。 





(5) 测试 配置 信息 是 否 有 错误 











在 不 启动 Nginx 的 情况 下 ， 使 用 -t 参 数 仅 测试 配置 文件 是 否 有 错误 。 
例如 : 





/usr/local/nginx/sbin/nginx -t 








执行 结果 中 显示 配置 是 否 正确 。 





(6) 在 测试 配置 阶段 不 输出 信息 


测试 配置 选项 时 ， 使 用 -gq 参数 可 以 不 把 error 级 别 以 下 的 信息 输出 到 
屏幕 。 例 如 : 





/usr/local/nginx/sbin/nginx -t -q 








(7) 显示 版 本 信息 


使 用 -v 参 数 显 示 Nginx 的 版 本 信息 。 例 如 : 





/usr/local/nginx/sbin/nginx -V 





(8) 显示 编译 阶段 的 参数 





使 用 -V 参 数 除 了 可 以 显示 Nginx 的 版 本 信息 外 ， 还 可 以 显示 配置 编 
译 阶 段 的 信息 ， 如 GCC 编 译 器 的 版 本 、 操 作 系 统 的 版 本 、 执 行 configure 
时 的 参数 等 。 例 如 : 





/usr/local/nginx/sbin/nginx -V 





(9) 快速 地 停止 服务 


使 用 -s stop 可 以 强制 停止 Nginx 服 务 。-s 参 数 其 实 是 告诉 Nginx 程 序 
向 正在 运行 的 Nginx 服 务 发 送信 号 量 ，Nginx 程 序 通过 nginx.pid 文 件 中 得 
到 master 进 程 的 进程 ID， 再 向 运行 中 的 master 进 程 发 送 TERM 信 号 来 快速 
地 关闭 Nginx 服 务 。 例 如 : 





/usr/local/nginx/sbin/nginx -s stop 





实际 上 ， 如 果 通 过 k 记 ll 命令 直接 应 es master 进 程 发 送 TERM 或 者 
INT 信 号 ， 效 果 是 一 样 的 。 例 如 ， 先 通过 ps 命令 来 查看 nginx master 的 进 
程 ID: 





:ahf5wapioo1l:root > ps -ef | grep nginx 
root 10800 1 0 02:27 ? 00:00:00 nginx: master process ./nginx 
root 10801 10800 0 02:27 ? 00:00:00 nginx: worker process 





接 下 来 直接 通过 kill 命 令 来 发 送信 和 号: 





kill -s SIGTERM 10800 





或 者 : 





kill -s SIGINT 10800 





上 述 两 条 命令 的 效果 与 执行 /usr/local/nginx/sbin/nginx-s stop 是 完全 
= 的 O 


(10)“ 优 雅 ” 地 停止 服务 


如 果 和 希望 Nginx 服 务 可 以 正常 地 处 理 完 当 前 所 有 请 求 再 停止 服务 ， 
那么 可 以 使 用 -s quit 参数 来 停止 服务 。 例 如 : 





/usr/local/nginx/sbin/nginx -s quit 





该 命令 与 快速 停止 Nginx 服 务 是 有 区 别 的 。 当 快 速 停止 服务 时 ， 
worker 进 程 与 naster 进 程 在 收 到 信号 后 会 立刻 跳出 循环 ， 退 出 进程 。 
而 “优雅 "地 停止 服务 时 ， 首 先 会 关闭 监听 端口 ， 停 止 接收 新 的 连接 ， 然 
后 把 当前 正在 处 理 的 连接 全 部 处 理 完 ， 最 后 再 退出 进程 。 





与 快速 停止 服务 相似 ， 可 以 直接 发 送 QUIT 信 和 号 给 master 进 程 来 俘 目 
服务 ， 其 效果 与 执行 -s quit 命 令 是 一 样 的 。 例 如 : 





kill -s SIGQUIT <nginx master pid> 





如 果 希 望 “优雅 ”地 停止 某 个 worker 进 程 ， 那 么 可 以 通过 向 该 进程 发 
送 WINCH 信 和 号 来 停止 服务 。 例 如 : 





kill -s SIGWINCH <nginx worker pid> 





(11) 使 运行 中 的 Nginx 重 读 配置 项 并 生效 


使 用 -s reload 参 数 可 以 使 运行 中 的 Nginx 服 务 重新 加 载 nginx.conf 文 
件 。 例 如 : 





/usr/local/nginx/sbin/nginx -s reload 





事实 上 ，Nginx 会 先 检查 新 的 配置 项 是 否 有 误 ， 如 果 全 部 正确 就 
以 “优雅 ”的 方式 关闭 ， 再 重新 启动 Nginx 来 实现 这 个 目的 。 类 似 的 ，-s 是 
发 送信 号 ， 仍 然 可 以 用 Kill 命令 发 送 HUP 信 和 号 来 达到 相同 的 效果 。 





kill -s SIGHUP <nginx master pid> 





(12) 日 志文 件 回 深 


使 用 -s reopen 参 数 可 以 重新 打开 日 志文 件 ， 这 样 可 以 先 把 当前 日 志 


文件 改名 或 转移 到 其 他 目录 中 进行 备份 ， 再 重新 打开 时 惑 会 生成 新 的 日 
志文 件 。 这 个 功能 使 得 日 志文 件 不 至 于 过 大 。 例 如 : 





/usr/local/nginx/sbin/nginx -s reopen 





当然 ， 这 与 使 用 kill 命 令 发 送 USR1 信 和 号 效果 相同 。 





kill -s SIGUSR1 <nginx master pid> 





(13) 平滑 升级 Nginx 


当 Nginx 服 务 升 级 到 新 的 版 本 时 ， 必 须要 将 旧 的 二 进 制 文件 Nginx 蔡 
换 控 ， 通 常情 况 下 这 是 需要 重 局 服务 的 ， 但 Nginx 文 持 不 重启 服务 来 完 
成 新 版 本 的 平滑 升级 。 








升级 时 包括 以 下 步 又， 





通知 正在 运行 的 旧版 本 Nginx 准 备 升级 。 通 过 向 master 进 程 发 送 
USR2 信 号 可 达到 目的 。 例 如 : 





kill -s SIGUSR2 <nginx master pid> 





这 时 ， 运 行 中 的 Nginx 会 将 pid 文 件 重 命名 ， 如 
将 /usr/local/nginx/logs/nginx.pid 香 命名 
为 /usr/local/nginx/logs/nginx.pid.oldbin， 这 样 新 的 Nginx 才 有 可 能 启动 成 


功 。 


2) 启动 新 版 本 的 Nginx， 可 以 使 用 以 上 介绍 过 的 任意 一 种 启动 方 
法 。 这 时 通过 ps 命令 可 以 发 现 新 旧版 本 的 Nginx 在 同时 运行 。 


3) 通过 kill 命 令 向 旧版 本 的 master 进 程 发 送 SIGQUIT 信 号 ， 以 “ 优 
雅 ” 的 方式 关闭 旧版 本 的 Nginx。 随 后 将 只 有 新 版 本 的 Nginx 服 务 运行 ， 
此 时 平滑 升级 完毕 。 


(14) 记 显示 命 令 行 帮助 





使 用 -h 或 者 -? 参 数 会 显示 文 持 的 所 有 命令 行 参 数 。 


17 小结 


本 童 介绍 了 Nginx 的 特点 以 及 在 什么 场景 下 需要 使 用 Nginx， 同 时 介 
绍 了 如 何 获取 Nginx 以 及 如 何 配置 、 编 译 、 安 装运 行 Nginx。 本 章 还 深入 
介绍 了 最 为 复杂 的 configure 过 程 ， 这 部 
三 部 分 的 基础 。 
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第 2 章 ”Nginx 的 配置 











Nginx 拥 有 大 量 官方 发 布 的 模块 和 第 三 方 模块 ， 这 些 已 有 的 模块 可 
以 帮助 我 们 实现 Web 服 务 嚣 上 很 多 的 功能 。 使 用 这 些 模 块 时 ， 仪 仪 需要 
增加 、 修 改 一 些 配置 项 即 可 。 因 此 ， 本 章 的 目的 是 熟悉 Nginx 的 配置 文 
件 ， 包 括 配置 文件 的 语法 格式 、 0 
置 以 及 使 用 HTTP 核 心 模 块 配置 静态 Web 服 务 器 的 方法 ， 最 后 还 会 介 2 
反问 代理 服务 器 。 








通过 本 章 的 学 习 ， 读 者 可 以 : 熟练 地 配置 一 个 静态 Web 服 务 占 ;对 
影响 Web 服 务 露 性 能 的 各 个 配置 项 有 深入 的 理解 ， 对 配置 语法 有 全 面 的 
了 解 。 通 过 互联 网 或 其 他 途径 得 到 任意 模块 的 配置 说 明 ， 然 后 可 通过 修 
改 nginx.conf 文 件 来 使 用 这 些 模块 的 功能 





2.1 运行 中 的 Nginx 进 程 间 的 关系 


在 正式 提供 服务 的 产品 环境 下 ， 部 署 Nginx 时 都 是 使 用 一 个 master 进 
程 来 管理 多 个 worker 进 程 ， 一 般 情 况 下 ，worker 进 程 的 数量 与 服务 器 上 
的 CPU 核心 数 相 等 。 每 一 个 worker 进 程 都 是 繁忙 的 ， 它 们 在 真正 地 提供 
互联 网 服务 ，master 进 程 则 很 “清闲 ?"， 只 负责 监控 管理 worker 进 程 。 
worker 进 程 之 间 通 过 共享 内 存 、 原 子 操作 等 一 些 进 程 间 通 信 机 制 来 实现 
负载 均衡 等 功能 (第 9 章 将 会 介绍 负载 均衡 机 制 ， 第 14 章 将 会 介绍 负载 
均衡 锁 的 实现 ) 。 





部 署 后 Nginx 进 程 间 的 关系 如 图 2-1 所 示 。 


Nginx 是 文 持 单 进程 《master 进程 ) 提供 服务 的 ， 那 么 为 什么 产品 环 
境 下 要 按照 master-worker 方 式 配置 同时 启动 多 个 进程 呢 ? 这 样 做 的 好 处 
主要 有 以 下 两 点 : 


“ 由 于 mastet 进 程 不 会 对 用 户 请 求 提供 服务 ， 只 用 于 管理 真正 提供 
服务 的 worket 进 程 ， 所 以 mastet 进 程 可 以 是 唯一 的 ， 它 仅 专 注 于 自己 的 
纯 管理 工作 ， 为 管理 员 提 供 命令 行 服务 ， 包 括 诸如 启动 服务 、 停 止 服 
务 、 重 载 配置 文件 、 平 滑 升 级 程序 等 。mastet 进 程 需要 拥有 较 大 的 权 
限 ， 例 如 ， 通 常会 利用 toot 用 户 启动 mastef 进 程 。wotket 进 程 的 权限 要 小 
于 或 等 于 mastet 进 程 ， 这 样 master 进 程 才 可 以 完全 地 管理 worket 进 程 。 当 


任意 一 个 wotket 进 程 出 现 错误 从 而 导致 cofedump 时 ，mastet 进 程 会 立刻 


局 动 新 的 wotket 进 程 继 续 服务 。 


.多 个 wotkef 进 程 处 理 互联 网 请 求 不 但 可 以 提高 服务 的 健 闪 性 (一 
个 wotket 进 程 出 错 后 ， 其 他 wotket 进 程 仍然 可 以 正常 提供 服务 ) ， 最 重 
要 的 是 ， 这 样 可 以 充分 利用 现在 常见 的 SMP 多 核 架 构 ， 从 而 实现 微观 上 
真正 的 多 核 并 发 处 理 。 因 此 ， 用 一 个 进程 (mastet 进 程 ) 来 处 理 互 联网 
请 求 肯定 是 不 合适 的 。 另 外 ， 为 什么 要 把 workert 进 程 数 量 设置 得 与 CPU 
核心 数量 一 致 呢 ?这 正 是 Nginx 与 Apache 服 务 器 的 不 同 之 处 。 在 Apache 
上 每 个 进程 在 一 个 时 刻 只 处 理 一 个 请 求 ， 因 此 ， 如 果 希 望 Web 服 务 器 拥 
有 并 发 处 理 的 请 求 数 更 多 ， 就 要 把 Apache 的 进程 或 线程 数 设置 得 更 多 ， 
通常 会 达到 一 台 服 务 器 拥有 几 百 个 工作 进程 ， 这 样 大 量 的 进程 间 切 换 将 
带 来 无 谓 的 系统 资源 消耗 。 而 Nginx 则 不 然 ， 一 个 worker 进 程 可 以 同时 处 
理 的 请 求 数 只 受 限于 内 存 大 小 ， 而 且 在 架构 设计 上 ， 不同 的 worket 进 程 
之 间 处 理 并 发 请 求 时 几乎 没有 同步 锁 的 限制 ，wotket 进 程 通常 不 会 进入 
睡眠 状态 ， 因 此 ， 当 Nginx 上 的 进程 数 与 CPU 核心 数 相等 时 〔( 最 好 每 一 


个 wotket 进 程 都 绑 定 特定 的 CPU 核心 ) ， 进 程 间 切 换 的 代价 是 最 小 的 。 
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图 2-1 部 署 后 Nginx 进 程 间 的 关系 


举例 来 说 ， 如 果 产 品 中 的 服务 器 CPU 核心 数 为 8， 那 么 就 需要 配置 8 
个 worker 进 程 ( 见 图 2-2) 。 


SHR 8$ %CPU 





图 2-2 ”worker 进 程 的 数量 尽量 与 CPU 核 心 数 相等 


如 有 果 对 路 径 部 分 都 使 用 默认 配置 ， 那 么 Nginx 运 行 目 录 
为 /usr/local/nginx， 其 目录 结构 如 下 。 





|---sbin 
| |---nginx 


|---koi-win 
|---koi-utf 
|---win-utf 
|---mime,types 
|---mime.types.default 
|---fastcgi_params 
|---fastcgi params.default 
|---fastcgi.conf 
|---fastcgi.conf.default 
|---uwsgi_params 
|---uwsgi_params.default 
|---scgi_params 
|---scgi_params.default 
|---nginx.conf 
|---nginx.conf.default 
---logs 
|---error.1log 
|---access.1og 
|---nginx.pid 
---html 


|---50x.html 

|---index.html 
---Client_body_temp 
---proxy_temp 
|---fastcgi_temp 
|---uwsgi_temp 
|---scgi_temp 


EE | 


2.2 Nginx 配 置 的 通用 语法 


Nginx 的 配置 文件 其 实 是 一 个 普通 的 文本 文件 。 下 面 来 看 一 个 简单 
的 例子 。 





user nobody; 
worker_processes 8,; 
error_log /var/log/nginx/error.1log error; 
#pid logs/nginx.pid; 
events { 
use epoll; 
worker_connections 50000; 


} 
http { 
include mime.types; 
default_type application/octet-stream; 
log format main '$remote addr [$time_ local] "$request" ' 
'$status $bytes_sent "$http_referer" ' 
'"$http_user_agent" "$http_x_forwarded_for"'; 
access 10g logs/access.1l0og main buffer=32k; 





» 


在 这 段 简短 的 配置 代码 中 ， 每 一 行 配置 项 的 语法 格式 都 将 在 2.2.2 市 
介绍 ， 出 现 的 events 和 http 块 配置 项 将 在 2.2.1 节 介绍 ， 以 # 符 号 开头 的 注 


释 将 在 2.2.3 节 介绍 ， 类 似 “buffer=32k” 这 样 的 配置 项 的 单位 将 在 2.2.4 节 


2.2.1 块 配 置 项 





块 配置 项 由 一 个 块 配置 项 名 和 一 对 大 括号 组 成 。 具 体 示例 如 下 : 


events {:: 


} 
http { 
upstream backend { 

server 127.0.0.1:8080,; 


gzip on; 
server { 


location /webstatic { 
gzip off; 
} 


上 面 代 码 段 中 的 events、http、server、location、upstream 等 都 是 块 
配置 项 ， 块 配置 项 之 后 是 否 如 “location/webstatic{.….}” 那 样 在 后 面 加 上 参 
数 ， 取 决 于 解析 这 个 块 配 置 项 的 模块 ， 不 能 一 概 而 论 ， 但 块 配置 项 一 定 
会 用 大 括号 把 一 系列 所 属 的 配置 项 全 包含 进来 ， 表 示 大 括号 内 的 配置 项 
同时 生效 。 所 有 的 事件 类 配置 都 要 在 events 块 中 ，http、server 等 配置 也 


如 循 这 个 规定 。 














块 配置 项 可 以 从 套 。 内 层 块 直接 继承 外 层 块 ， 例 如 ， 上 例 中 ， 
server 块 里 的 任意 配置 都 是 基于 http 块 里 的 已 有 配置 的 。 当 内 外 层 块 中 的 
配置 发 生 冲 突 时 ， 究 竞 是 以 内 层 块 还 是 外 层 块 的 配置 为 准 ， 取 决 于 解析 
这 个 配置 项 的 模块 ， 第 4 章 将 会 介绍 http 块 内 配置 项 冲突 的 处 理 方法 。 例 
如 ， 上 例 在 http 模 块 中 已 经 打开 了 “gzip on;”， 但 其 下 的 location/webstatic 











又 把 gzip 关 闭 了 : gzip off;， 最 终 ， 在 /webstatic 的 处 理 模块 中 ，gzip 模 块 
是 按照 gzip off 来 处 理 请 求 的 。 


2.2.2 ”配置 项 的 语法 格式 


从 上 文 的 示例 可 以 看 出 ， 最 基本 的 配置 项 语法 格式 如 下 : 


配置 项 名 
配置 项 值 
1 配置 项 值 


Da 





下面 解释 一 下 配置 项 的 构成 部 分 。 





首先 ， 在 行 首 的 是 配置 项 名 ， 这 些 配置 项 名 必须 是 Nginx 的 茶 一 个 
模块 想 要 处 理 的， 否则 Nginx 会 认为 配置 文件 出 现 了 非法 的 配置 项 名 。 
配置 项 名 输入 结束 后 ， 将 以 空格 作为 分 隔 符 。 


其 次 是 配置 项 值 ， 它 可 以 是 数字 或 字符 串 《〈 当 然 也 包括 正则 表达 
式 ) 。 针 对 一 个 配置 项 ， 既 可 以 只 有 一 个 值 ， 也 可 以 包含 多 个 值 ， 配 置 
项 值 之 间 仍 然 由 空格 符 来 分 隔 。 当 然 ， 一 个 配置 项 对 应 的 值 究 竟 有 多 少 
个 ， 取 决 于 解析 这 个 配置 项 的 模块 。 我 们 必须 根据 某 个 Nginx 模 块 对 一 


个 配置 项 的 约定 来 更 改 配置 项 ， 第 4 章 将 会 介绍 模块 是 如 何 约定 一 个 配 
置 项 的 格式 。 





最 后 ， 每 行 配置 的 结尾 需要 加 上 分 号 。 


@ 注意 “如果 配置 项 值 中 包括 语法 符号 ， 比 如 空格 符 ， 那 么 需要 
使 用 单 引 号 或 双 引 号 括 住 配 置 项 值 ， 否 则 Nginx 会 报 语法 错误 。 例 如 : 





log format main '$remote addr - $remote user [$time _ local] "$request" '; 





2.2.3 ”配置 项 的 注释 


如 果 有 一 个 配置 项 暂时 需要 注释 掉 ， 那 么 可 以 加 “#” 注 释 掉 这 一 行 
配置 。 例 如 : 





#pid logs/nginx.pid; 





2.2.4 配置 项 的 单位 





大 部 分 模块 遵循 一 些 通 用 的 规定 ， 如 指定 空间 大 小 时 不 用 每 次 都 定 
义 到 字 节 、 指 定时 间 时 不 用 精确 到 坚 秒 。 


当 指 定 空间 大 小 时 ， 可 以 使 用 的 单位 包括 : 


. KK 或 者 k 千 字 节 (KiloByte，KB) 。 
* M 或 者 m 兆 字 节 (MegaByte，MB) 。 


例如 : 





gzip_buffers 4 8k; 
client_ max_body_size 64M; 





当 指 定时 间 时 ， 可 以 使 用 的 单位 包括 : 


ms (上 毫秒) ，s( 秒 ) ，m (分 钟 ) ，h (小 时 ) , d (天 ) ， 
Ww ( 周 ， 包 含 7 天 ) ，M (月 ， 包 含 30 天 ) ，y (年 ， 包 含 365 天 ) 。 





例如 : 
expires 10y; 
proxy_read_timeout 600; 
client_body_timeout 2m; 





人 @@ ;ij 总 ”配置 项 后 的 值 完 竟 是 否 可 以 使 用 这 些 单位 ， 取 决 于 解析 
该 配置 项 的 模块 。 如 果 这 个 模块 使 用 了 Nginx 框 架 提供 的 相应 解析 配置 
项 方法 ， 那 么 配置 项 值 才 可 以 携带 单位 。 第 4 章 中 详细 描述 了 Nginx 框 架 


提供 的 14 种 预 设 解析 方法 ， 其 中 一 些 方法 将 可 以 解析 以 上 列 出 的 单位 。 


2.2.5 在 配置 中 使 用 变量 





有 些 模 块 允 许 在 配置 项 中 使 用 变量 ， 如 在 日 志 记录 部 分 ， 有 具体 示例 
Wi fs 





log format main '$remote addr - $remote user [$time _ local] "$request" ' 
'$status $bytes_sent "$http_referer" ' 
'"$http_user_agent" "$http_x_forwarded_for"'; 





其 中 ，remote_addr 是 一 个 变量 ， 使 用 它 的 时 候 前 面 要 加 上 $ 符 号。 
需要 注意 的 是 ， 这 种 变量 只 有 少数 模块 支持 ， 并 不 是 通用 的 。 


许多 模块 在 解析 请 求 时 都 会 提供 多 个 变量 (如 本 章 后 面 提 到 的 http 
core module、http proxy module、http upstream module 等 ) ， 以 使 其 他 模 
块 的 配置 可 以 即时 使 用 。 我 们 在 学 习 某 个 模块 提供 的 配置 说 明 时 可 以 关 


注 它 是 否 提 供 变量 。 


全 提示 。 在 执行 configure 命 令 时 ， 我 们 已 经 把 许多 模块 编译 进 
Nginx 中 ， 但 是 否 启 用 这 些 模块 ， 一 般 取决 于 配置 文件 中 相应 的 配置 
项 。 换 多 话说 ， 每 个 Nginx 模 块 都 有 自己 感 兴趣 的 配置 项 ， 大 部 分 模块 
都 必须 在 nginx.conf 中 读 取 某 个 配置 项 后 才 会 在 运行 时 启用 。 例 如 ， 只 有 
当 配 置 http{...} 这 个 配置 项 时 ，ngx_http_module 模 块 才 会 在 Nginx 中 局 
用 ， 其 他 依赖 hex_http_module 的 模块 也 才能 正常 使 用 。 


2.3 Nginx 服 务 的 基本 配置 


Nginx 在 运行 时 ， 至 少 必须 加 载 几 个 核心 模块 和 一 个 事件 类 模块 。 
这 些 模块 运行 时 所 支持 的 配置 项 称 为 基本 配置 一 所 有 其 他 模块 执行 时 
都 依赖 的 配置 项 。 

下 面 详 述 基本 配置 项 的 用 法 。 由 于 配置 项 较 多 ， 所 以 把 它们 按照 用 
户 使 用 时 的 预期 功能 分 成 了 以 下 4 类 ; 


用 于 调 武 、 定 位 问题 的 配置 项 。 
` 正常 运行 的 必 备 配置 项 。 
优化 性 能 的 配置 项 。 


事件 类 配置 项 《有些 事件 类 配置 项 归纳 到 优化 性 能 类 ， 这 是 因为 
它们 虽然 也 属于 events{} 块 ， 但 作用 是 优化 性 能 ) 。 


有 这 人 么 一 些 配置 项 ， 即 使 没有 显 式 地 进行 配置 ， 它 们 也 会 有 默认 的 
值 ， 如 daemon， 即 使 在 nginx.conf 中 没有 对 它 进 行 配置 ， 也 相当 于 打开 
了 这 个 功能 ， 这 扣 需 要 注意 。 对 于 这 样 的 配置 项 ， 作 者 会 在 下 面相 应 的 
配置 项 描述 上 加 入 一 行 “ 默 认 : ”来 进行 说 明 。 





2.3.1 用 于 调试 进程 和 定位 问题 的 配置 项 


先 来 看 一 下 用 于 调试 进程 、 定 位 问题 的 配置 项 ， 如 下 所 示 。 





(1) 是 否 以 守护 进程 方式 运行 Nginx 
语法 : daemon onloff; 
四 认 : daemon on 


守护 进程 (daemon) 是 脱离 终端 并 且 在 后 人 台 运 行 的 进程 。 它 脱离 终 
端 是 为 了 避免 进程 执行 过 程 中 的 信息 在 任何 终端 上 显示 ， 这 样 一 来 ， 进 
程 也 不 会 被 任何 终端 所 产生 的 信息 所 打 断 。Nginx 坚 无 疑问 是 一 个 需要 
以 守护 进程 方式 运行 的 服务 ， 因 此 ， 默 认 都 是 以 这 种 方式 运行 的 。 








不 过 Nginx 还 是 提供 了 关闭 守护 进程 的 模式 ， 之 所 以 提供 这 种 模 
式 ， 是 为 了 方便 跟 踩 调试 Nginx， 毕 竟 用 gdb 调 试 进程 时 最 烦琐 的 就 是 如 
何 继续 跟 进 fork 出 的 子 进程 了 。 这 在 第 三 部 分 研究 Nginx 架 构 时 很 有 用 。 


(2) 是 否 以 master/worker 方 式 工作 
语法 : master_process on|off; 
默认 : master_process on; 


可 以 看 到 ， 在 如 图 2-1 所 示 的 产品 环境 中 ， 是 以 一 个 master 进 程 管理 


多 个 worker 进 程 的 方式 运行 的 ， 几 乎 所 有 的 产品 环境 下 ，Nginx 都 以 这 
种 方式 工作 。 


与 daemon 配 置 相同 ， 提 供 master_process 配 置 也 是 为 了 方便 跟踪 调 
试 Nginx。 如 果 用 off 关 闭 了 master_process 方 式 ， 束 不 会 fork 出 worker 子 
进程 来 处 理 请 求 ， 而 是 用 master 进 程 自身 来 处 理 请 求 。 


(3) error 日 志 的 设置 
语法 : ”error_log/path/file level; 


于 认 : error_log logs/error.log error; 





error 日 志 是 定位 Nginx 问 题 的 最 佳 工具 ， 我 们 可 以 根据 目 己 的 需求 


妥善 设置 error 日 志 的 路 径 和 级 别 。 


/patb/file 参 数 可 以 是 一 个 具体 的 文件 ， 例 如 ， 默 认 情 况 下 是 
logs/error.log 文 件 ， 最 好 将 它 放 到 一 个 磁盘 空间 足够 大 的 位 置 ， /pathyfile 
也 可 以 是 /dev/null， 这 样 就 不 会 输出 任何 日 志 了 ， 这 也 是 关闭 error 日 志 
的 唯一 手段 ，/path/file 也 可 以 是 stderr， 这 样 日 志 会 输出 到 标准 错误 文件 
中 。 





level 是 日 志 的 输出 级 别 ， 取 值 范围 是 debug、info、notice、warmn、 
error、crit、alert、emerg， 从 左 至 右 级 别 依次 增 大 。 当 设 定 为 一 个 级 别 


时 ， 大 于 或 等 于 该 级 别 的 日 志 都 会 被 输出 到 /path/fle 文 件 中 ， 小 于 该 级 





别 的 日 志 则 不 会 输出 。 例 如 ， 当 设 定 为 error 级 别 时 ，error、crit、alert、 


emerg 级 别 的 日 志 都 会 输出 。 


如 果 设 定 的 日 志 级 别 是 debug， 则 会 输出 所 有 的 日 志 ， 这 样 数据 量 
会 很 大 ， 需 要 预先 确保 /path/file 所 在 磁盘 有 足够 的 磁盘 空间 。 


@ 注意 ”如 果 日 志 级 别 设 定 到 debug， 必 须 在 configure 时 加 入 -- 


with-debug 配 置 项 。 
(4) 是 否 处 理 几 个 特殊 的 调试 点 
语法 : debug_points[stoplabort] 


这 个 配置 项 也 是 用 来 帮助 用 户 跟踪 调试 Nginx 的 。 它 接受 两 个 参 
数 : stop 和 abort。Nginx 在 一 些 关 键 的 错误 逻辑 中 (Nginx 1.0.14 版 本 中 
有 8 处 ) 设置 了 调试 点 。 如 果 设 置 了 debug_points 为 stop， 那 么 Nginx 的 代 
码 执行 到 这 些 调 试点 时 就 会 发 出 SIGSTOP 信 号 以 用 于 调试 。 如 果 
debug_points 设 置 为 abort， 则 会 产生 一 个 coredump 文 件 ， 可 以 使 用 gdb 来 
查看 Nginx 当 时 的 各 种 信息 。 


通常 不 会 使 用 这 个 配置 项 。 





(5) 仪 对 指定 的 客户 疹 输 出 debug 级 别 的 日 志 


语法 : ”debug_connection[IP|CIDR] 


这 个 配置 项 实际 上 属于 事件 类 配置 ， 因 此 ， 它 必须 放 在 eventst{...} 
中 才 有 效 。 它 的 值 可 以 是 IP 地 址 或 CIDR 地 址 ， 例 如 : 





events { 
debug_connection 10.224.66.14; 
debug_connection 10.224.57.0/24; 
} 





这 样 ， 仅 仅 来 自 以 上 IP 地 址 的 请 求 才 会 输出 debug 级 别 的 日 志 ， 其 
他 请 求 仍然 沿用 error_log 中 配置 的 日 志 级 别 。 





上 面 这 个 配置 对 修复 Bug 很 有 用 ， 特 别 是 定位 高 并 发 请 求 下 才 会 有 友 
生 的 问题 。 


@ 注意 ”使 用 debug_connection 前 ， 需 确保 在 执行 configure 时 已 经 


加 入 了 --with-debug 参 数 ， 否 则 不 会 生效 。 
(6) 限制 coredump 核 心 转 储 文件 的 大 小 
语法 : worker_rlimit_core size， 


在 Linux 系 统 中 ， 当 进程 发 生 错误 或 收 到 信号 而 终止 时 ， 系 统 会 将 
进程 执行 时 的 内 存 内 容 《〈《 核 心 映像 ) 写 入 一 个 文件 〈core 文 件 ) ， 以 作 
为 调试 之 用 ， 这 就 是 所 谓 的 核心 转 储 〈core dumps) 。 当 Nginx 进 程 出 现 
一 些 非法 操作 (如 内 存 越界 〉 导致 进程 直接 被 操作 系统 强制 结束 时 ， 会 
生成 核心 转 储 core 文 件 ， 可 以 从 core 文 件 获取 当时 的 堆栈 、 寄 存 器 等 信 








电 ， 从 而 帮助 我 们 定位 问题 。 但 这 种 core 文 件 中 的 许多 信息 不 一 定 是 用 
户 需 要 的 ， 如 果 不 加 以 限制 ， 那 么 可 能 一 个 core 文 件 会 达到 几 GB， 这 样 
随便 coredumps 几 次 就 会 把 磁盘 占 满 ， 引 发 严重 问题 。 通 过 

worker_rlimit_ core 配置 可 以 限制 core 文 件 的 大 小 ， 从 而 有 效 帮 助 用 户 定 


位 问题 。 





(7) 指定 coredump 文 件 生成 目录 
语法 : working_directory path; 


worker 进 程 的 工作 目录 。 这 个 配置 项 的 唯一 用 途 就 是 设置 coredump 
文件 所 放置 的 目录 ， 协 助 定位 问题 。 因 此 ， 需 确保 worker 进 程 有 权限 向 
working_directory 指 定 的 目录 中 写 入 文件 。 








2.3.2 ”正常 运行 的 配置 项 


下 面 是 正常 运行 的 配置 项 的 相关 介 

(1) 定义 环境 变量 

语法 : envVARIVAR=VALUE 

这 个 配置 项 可 以 让 用 户 直 接 设 置 操作 系统 上 的 环境 变量 。 例 如 : 


env TESTPATH=/tmp/; 


(2) 肉 入 其 他 配置 文件 
语法 : include/path/file; 


include 配 置 项 可 以 将 其 他 配置 文件 从 入 到 当前 的 nginx.conf 文 件 
中 ， 它 的 参数 既 可 以 是 绝对 路 径 ， 也 可 以 是 相对 路 径 〈 相 对 于 Nginx 的 
配置 目录 ， 即 nginx.conf 所 在 的 目录 ) ， 例 如 : 


include mime,types ; 
include vhost/*.conf,; 


可 以 看 到 ， 参 数 的 值 可 以 是 一 个 明确 的 文件 名 ， 也 可 以 是 含有 通 配 
符 * 的 文件 名 ， 同 时 可 以 一 次 暴 入 多 个 配置 文件 。 


(3) pid 文 件 的 路 径 
语法 : pid path/file; 
默认 : pid logs/nginx.pid; 


保存 master 进 程 ID 的 pid 文 件 存放 路 径 。 默 认 与 configure 执 行 时 的 参 
数 “--pid-path” 所 指定 的 路 径 是 相同 的 ， 也 可 以 随时 修改 ， 但 应 确保 
Nginx 有 权 在 相应 的 目标 中 创建 pid 文 件 ， 该 文件 直接 影响 Nginx 是 否 
以 运行 。 


(4) Nginx worker 进 程 运行 的 用 户 及 用 户 组 


语法 : user username[groupname]; 


默认 : user nobody nobody; 


user 用 于 设置 master 进 程 启动 后 ，fork 出 的 worker 进 程 运行 在 哪个 用 
户 和 用 户 组 下 。 当 按照 “user username:” 设 置 时 ， 用 户 组 名 与 用 户 名 相 
同 。 


若 用 户 在 configure 命 令 执行 时 使 用 了 参数 --user=username 和 -- 


group=groupname， 此 时 nginx.conf 将 使 用 参数 中 指定 的 用 户 和 用 户 组 。 


(5) 指定 Nginx worker 进 程 可 以 打开 的 最 大 句柄 描述 符 个 数 


语法 : worker_rlimit nofile limit; 


设置 一 个 worker 进 程 可 以 打开 的 最 大 文件 句柄 数 。 
(6) 限制 信号 队列 


语法 : worker_rlimit_sigpending limit; 


设置 每 个 用 户 发 往 Nginx 的 信号 队列 的 大 小 。 也 就 是 说 ， 当 某 个 用 
尸 的 信号 队列 满 了 ， 这 个 用 户 再 发 送 的 信和 与 量 会 被 丢 挥 。 





2.3.3 ”优化 性 能 的 配置 项 


下 面 是 优化 性 能 的 配置 项 的 相关 介绍 。 
(1) Nginx worker 进 程 个 数 

语法 : worker_processes number; 

默认 : worker_processes 1; 


在 master/worker 运 行 方式 下 ， 定 义 worker 进 程 的 个 数 。 





worker 进 程 的 数量 会 直接 影响 性 能 。 那 么 ， 用 户 配 置 多 少 个 worker 
进程 才 好 呢 ? 这 实际 上 与 业务 需求 有 关 。 





每 个 worker 进 程 都 是 单线 程 的 进程 ， 它 们 会 调用 各 个 模块 以 实现 多 
种 多 样 的 功能 。 如 果 这 些 模块 确认 不 会 出 现 阻 塞 式 的 调用 ， 那 么 ， 有 多 
少 CPU 内 核 就 应 该 配置 多 少 个 进程 ; 反之， 如 果 有 可 能 出 现 阻 塞 式 调 
用 ， 那 么 需要 配置 稍 多 一 些 的 worker 进 程 。 








例如 ， 如 果 业 务 方面 会 致使 用 户 请 求 大 量 读 取 本 地 磁盘 上 的 静态 资 
源 文件 ， 而 且 服 务 器 上 的 内 存 较 小 ， 以 至 于 大 部 分 的 请 求 访问 静态 资源 
文件 时 都 必须 读 取 磁盘 〔 磁 头 的 寻 址 是 缓慢 的 ) ， 而 不 是 内 存 中 的 磁盘 
绥 存 ， 那 么 磁盘 IO 调用 可 能 会 阻塞 住 worker 进 程 少 量 时 间 ， 进 而 导致 服 
务 整 体 性 能 下 降 。 


多 worker 进 程 可 以 充分 利用 多 核 系 统 架 构 ， 但 知 worker 进 程 的 数量 


多 于 CPU 内 核 数 ， 那 么 会 增 大 进程 间 切 换 带 来 的 消耗 〈Linux 是 抢占 式 
内 核 ) 。 一 般 情 况 下 ， 用 户 要 配置 与 CPU 内 核 数 相等 的 worker 进 程 ， 并 
且 使 用 下 面 的 worker_cpu_affinity 配 置 来 绑 定 CPU 内 核 。 


(2) 绑 定 Nginx worker 进 程 到 指定 的 CPU 内 核 


语法 : worker_cpu_affinity cpumask[cpumask...] 


Jj zz 人 = 


为 什么 要 绑 定 worker 进 程 到 指定 的 CPU 内 核 呢 ? 假定 每 一 个 worker 
进程 都 是 非常 繁忙 的 ， 如 果 多 个 worker 进 程 都 在 抢 同 一 个 CPU， 那 么 这 
就 会 出 现 同步 问题 。 反 之 ， 如 果 每 一 个 worker 进 程 都 独 享 一 个 CPU， 就 
在 内 核 的 调度 策略 上 实现 了 完全 的 并 发 。 


例如 ， 如 果 有 4 条 CPU 内 核 ， 就 可 以 进行 如 下 配置 : 





worker_processes 4; 
worker_cpu_affinity 1000 0100 0010 0001; 





@ 注意 worker_cpu_affinity 配 置 仅 对 Linux 操 作 系 统 有 效 。Linux 操 


作 系 统 使 用 sched_setaffinity0 系 统 调用 实现 这 个 功能 。 
(3) SSL 硬 件 加 速 
语法 : ssl_engine device; 


如 果 服 务 器 上 有 SSL 硬 件 加 速 设备 ， 那 么 就 可 以 进行 配置 以 加 快 














SSL 协 议 的 处 理 速 度 。 用 户 可 以 使 用 OpenSSL 提 供 的 命令 来 查看 是 否 有 
SSL 人 硬件 加 速 设 备 : 





openssl] engine -t 





(4) 系统 调用 gettimeofday 的 执行 频率 
语法 : timer_resolution t: 


默认 情况 下 ， 每 次 内 核 的 事件 调用 (如 epoll、select、poll、kqueue 
等 ) 返回 时 ， 都 会 执行 一 次 gettimeofday， 实 现 用 内 核 的 时 钟 来 更 新 
Nginx 中 的 缓存 时 钟 。 在 早期 的 Linux 内 核 中 ，gettimeofday 的 执行 代价 不 
小 ， 因 为 中 间 有 一 次 内 核 态 到 用 户 态 的 内 存 复制 。 当 需要 降低 
gettimeofday 的 调用 频率 时 ， 可 以 使 用 timer_resolution 配 置 。 例 
如 ，“timer_resolution 100ms; ”表示 至 少 每 100ms 才 调用 一 次 


gettimeofday 。 


但 在 目前 的 大 多 数 内 核 中 ， 如 x86-64 体 系 架 构 ，gettimeofday 只 是 一 
次 vsyscall， 仪 仪 对 共有 至 内 存 页 中 的 数据 做 访问 ， 并 不 是 通常 的 系统 调 
用 ， 代 价 并 不 大 ， 一 般 不 必 使 用 这 个 配置 。 而 且 ， 如 果 希 望 日 志文 件 中 
每 行 打印 的 时 间 更 准确 ， 也 可 以 使 用 它 。 











(5) Nginx worker 进 程 优先 级 设置 


语法 : worker_priority nice; 
默认 : worker_priority 0; 
该 配置 项 用 于 设置 Nginx worker 进 程 的 nice 优 先 级 。 


在 Linux 或 其 他 类 UNIX 操 作 系 统 中 ， 当 许多 进程 都 处 于 可 执行 状态 
时 ， 将 按照 所 有 进程 的 优先 级 来 决定 本 次 内 核 选 择 哪 一 个 进程 执行 。 进 
程 所 分 配 的 CPU 时 间 片 大 小 也 与 进程 优先 级 相关 ， 优 先 级 越 高 ， 进 程 分 
配 到 的 时 间 刻 也 就 越 大 《例如 ， 在 默认 配置 下， 最 小 的 时 间 片 只 有 
5ms， 最 大 的 时 间 片 则 有 800ms) 。 这 样 ， 优 先 级 高 的 进程 会 占有 更 多 
的 系统 资源 。 





优先 级 由 静态 优先 级 和 内 核 根 据 进 程 执行 情况 所 做 的 动态 调整 《〈 目 
前 只 有 +5 的 调整 ) 共同 决定 。nice 值 是 进程 的 静态 优先 级 ， 它 的 取 值 范 
围 是 -20~+19，-20 是 最 高 优先 级 ，+19 是 最 低 优 先 级 。 因 此 ， 如 果 用 户 
希望 Nginx 占 有 更 多 的 系统 资源 ， 那 么 可 以 把 nice 值 配置 得 更 小 一 些 ， 但 
不 建议 比 内 核 进程 的 nice 值 〈 通 常 为 -5) 还 要 小 。 





2.3.4 ”事件 类 配置 项 


下 面 是 事件 类 配置 项 的 相关 介绍 。 


(1) 是 否 打 开 accept 锁 


语法 : accept_mutex[on|off] 


默认 : accept_mutext on; 





accept_mutex 是 Nginx 的 负载 均衡 锁 ， 本 书 会 在 第 9 章 事 件 处 理 框 架 
中 详 述 Nginx 是 如 何 实现 负载 均衡 的 。 这 里 ， 读 者 仅 需 要 知道 
accept_mutex 这 把 锁 可 以 让 多 个 worker 进 程 轮流 地 、 序 列 化 地 与 新 的 客 
户 端 建立 TCP 连 接 。 当 某 一 个 worker 进 程 建立 的 连接 数量 达到 
worker_connections 配 置 的 最 大 连接 数 的 7/8 时 ， 会 大 大 地 减 小 该 worker 
进程 试图 建立 新 TCP 连 接 的 机 会 ， 以 此 实现 所 有 worker 进 程 之 上 处 理 的 
客户 端 请 求 数 尽量 接近 。 


accept 锁 默认 是 打开 的 ， 如 果 关 财 它 ， 那 么 建立 TCP 连接 的 耗 时 会 
更 短 ， 但 worker 进 程 之 间 的 负载 会 非常 不 均衡 ， 因 此 不 建议 关闭 它 。 


(2) lock 文件 的 路 径 
语法 : lock_file path/file; 
默认 : lock file logs/nginx.lock; 


accept 锁 可 能 需要 这 个 lock 文 件 ， 如 果 accept 锁 关闭 ，lock_file 配 置 
完全 不 生效 。 如 果 打 开 了 accept 锁 ， 并 且 由 于 编译 程序 、 操 作 系 统 架 构 
等 因素 导致 Nginx 不 文 持 原子 锁 ， 这 时 才 会 用 文件 锁 实 现 accept 锁 
《14.8.1 节 将 会 介绍 文件 锁 的 用 法 ) ， 这 样 lock_file 指 定 的 lock 文 件 才 会 








生效 


@ ,i 在 基于 i386、AMD64、Sparc64、PPC64 体 系 架构 的 操作 
系统 上 ， 若 使 用 GCC、Intel C++、SunPro C++ 编译 器 来 编译 Nginx， 则 
可 以 肯定 这 时 的 Nginx 是 支持 原子 锁 的 ， 因 为 Nginx 会 利用 CPU 的 特性 并 
用 汇编 语言 来 实现 它 (可 以 参考 14.3 节 x86 架 构 下 原子 操作 的 实现 ) 。 这 
时 的 lock_file 配 置 是 没有 意义 的 。 


(3) 使 用 accept 锁 后 到 真正 建立 连接 之 间 的 延迟 时 间 
语法 : accept_mutex_delay Nms; 
默认 : accept_mutex_delay 500ms; 


在 使 用 accept 锁 后 ， 同 一 时 间 只 有 一 个 worker 进 程 能 够 取 到 accept 
锁 。 这 个 accept 锁 不 是 阻 奢 锁 ， 如 果 取 不 到 会 立刻 返回 。 如 果 有 一 个 
worker 进 程 试图 取 accept 锁 而 没有 取 到 ， 它 至 少 要 等 accept_mutex_delay 
定义 的 时 间 间 隔 后 才能 再 次 试图 取 锁 。 


(4) 批量 建立 新 连接 
语法 : multi_accept[onloff]; 
默认 :_ multi_accept off; 


当 事 件 模型 通知 有 新 连接 时 ， 尽 可 能 地 对 本 次 调度 中 客户 端 发 起 的 


所 有 TCP 请 求 都 建立 连接 。 
(5) 选择 事件 模型 


语法 : use[kqueuelrtsiglepolll/devwpolllselectlpollleventport]; 





默认 : ”Nginx 会 自动 使 用 最 适合 的 事件 模型 。 





对 于 Linux 操 作 系 统 来 说 ， 可 供 选 择 的 事件 驱动 模型 有 poll、 
select、epoll 三 种 。epoll 当 然 是 性 能 最 高 的 一 种 ， 在 9.6 节 会 解释 epol] 为 
什么 可 以 处 理 大 并 发 连接 。 


(6) 每 个 worker 的 最 大 连接 数 
语法 : worker_connections number， 


定义 每 个 worker 进 程 可 以 同时 处 理 的 最 大 连接 数 。 





2.4 ”用 HTTP 核 心 模块 配置 一 个 静态 Web 服 务 器 


静态 Web 服 务 器 的 主要 功能 由 ngx_http_core_module 模 块 (HTTP 框 
架 的 主要 成 员 ) 实现 ， 当 然 ， 一 个 完整 的 静态 Web 服 务 器 还 有 许多 功能 
是 由 其 他 的 HITP 模 块 实现 的 。 本 节 主 要 讨论 如 何 配置 一 个 包含 基本 功 
能 的 静态 Web 服 务 器 ， 文 中 会 完整 地 说 明 ngx_http_core_module 模 块 提 供 
的 配置 项 及 变量 的 用 法 ， 但 不 会 过 多 说 明 其 他 HTTP 模 块 的 配置 项 。 在 
阅读 完 本 节 内 容 后 ， 读 者 应 当 可 以 通过 简单 的 查询 相关 模块 (如 
ngx_http_gzip_filter_ module、ngx_http_image_filter_ module 等 ) 的 配置 项 
说 明 ， 方 便 地 在 nginx.conf 配 置 文件 中 加 入 新 的 配置 项 ， 从 而 实现 更 多 
的 Web 服 务 器 功能 。 


除了 2.3 节 提 到 的 基本 配置 项 外 ， 一 个 典型 的 静态 Web 服 务 器 还 会 包 
含 多 个 server 块 和 location 块 ， 例 如 : 





http { 
gzip on; 
upstream { 


server { 
listen localhost:80; 


Jocation /webstatic { 
if … 


} 
root /opt/webresource; 


} 
location ~* .(jpgljpeglpng|ljpelgif)$ { 


} 


server { 





所 有 的 HTTP 配 置 项 都 必须 直属 于 http 块 、server 块 、location 块 、 
upstream 块 或 if 块 等 HTTP 配置 项 目 然 必须 全 部 在 http{} 块 之 内 ， 这 里 
的 “直属 于 ?是 指 配置 项 直接 所 属 的 大 括号 对 应 的 配置 块 ) ， 同 时 ， 在 描 
述 每 个 配置 项 的 功能 时 ， 会 说 明 它 可 以 在 上 述 的 哪个 块 中 存在 ， 因 为 有 
些 配 置 项 可 以 任意 地 出 现在 某 一 个 块 中 ， 而 有 些 配 置 项 只 能 出 现在 特定 
的 块 中 ， 在 第 4 章 介绍 自 定义 配置 项 的 读 取 时 ， 相 信 读 者 就 会 体会 到 这 
种 设计 思路 。 











Nginx 为 配置 一 个 完整 的 静态 Web 服 务 器 提供 了 非常 多 的 功能 ， 下 
面 会 把 这 些 配置 项 分 为 以 下 8 类 进行 详 述 : 虚拟 主机 与 请 求 的 分 用 、 文 





件 路 径 的 定义 、 内 存 及 磁盘 资源 的 分 配 、 网 络 连接 的 设置 、MIME 类 型 
的 设置 、 对 客户 站 请 求 的 限制 、 文 件 操 作 的 优化 、 对 客户 问 请 求 的 特殊 
处 理 。 这 种 划分 只 是 为 了 帮助 大 家 从 功能 上 理解 这 些 配置 项 。 


在 这 之 后 会 列 出 ngx_http_core_module 模 块 提 供 的 变量 ， 以 及 简单 
说 明 它 们 的 意义 。 





2.4.1 ”虚拟 主机 与 请 求 的 分 发 








由 于 了 P 地 址 的 数量 有 限 ， 因 此 经 常 存在 多 个 主机 域名 对 应 着 同一 个 
耳 地址 的 情况 ， 这 时 在 nginx.conf 中 就 可 以 按照 server_name《〈 对 应 用 户 
请 求 中 的 主机 域名 ) 并 通过 server 块 来 定义 虚拟 主机 ， 每 个 server 块 就 是 
一 个 虚拟 主机 ， 它 只 处 理 与 之 相对 应 的 主机 域名 请 求 。 这 样 ， 一 台 服 务 
器 上 的 Nginx 就 能 以 不 同 的 方式 处 理 访问 不 同 主机 域名 的 HITP 请 求 了 。 








(1) 监听 端口 


语法 : listen address:port[default(deprecated in 0.8.21)|default_server| 
[backlog=numlrcvbuf=sizelsndbuf=sizelaccept_ filter=filterldeferredlbindjipV6% 


[onloff]lssl]j]; 
默认 : listen 80; 


配置 块 : server 


listen 参 数 决 定 Nginx 服 务 如 何 监听 端口 。 在 listen 后 可 以 只 加 了 地 
址 、 端 口 或 主机 名 ， 非 常 灵活 ， 例 如 





listen 127.0.0.1:8000 
listen 127.0.0.1; # 注 意 : 不 加 端口 时 ， 默 认 监 听 


80 端 口 


listen 8000; 
listen *:8000; 
listen localhost:8000; 





如 果 服 务 器 使 用 IPv6 地 址 ， 那 么 可 以 这 样 使 用 : 





listen [::]:8000; 
listen [fe80::1]; 
listen [:::a8c9:;1234]:80; 





在 地 址 和 端口 后 ， 还 可 以 加 上 其 他 参数 ， 例 如 : 





lJisten 443 default_ server ssl; 
listen 127.0.0.1 default_ server accept _ filter=dataready backlog=1024; 





下 面 说 明 listen 可 用 参数 的 意义 。 


default: 将 所 在 的 servet 块 作为 整个 Web 服 务 的 默认 server 块 。 如 果 
没有 设置 这 个 和 参数， 那么 将 会 以 在 nginx.conf 中 找到 的 第 一 个 servert 块 作 
为 默认 server 块 。 为 什么 需要 默认 虚拟 主机 呢 ? 当 一 个 请 求 无 法 匹配 配 
置 文件 中 的 所 有 主机 域名 时 ， 就 会 选用 默认 的 虚拟 主机 (在 11.3 节 介绍 
默认 主机 的 使 用 ) 。 


-default _setvet: 同上 。 


. backlos=num: 表示 TCP 中 backlog 队 列 的 大 小 。 默 认为 -1， 表 示 

予 设置 。 在 TCP 建 立 三 次 握手 过 程 中 ， 进 程 还 没有 开始 处 理 监 听 句 
柄 ， 这 时 backlog 队 列 将 会 放置 这 些 新 连接 。 可 如 果 backlog 队 列 已 满 ， 还 
有 新 的 客户 端 试图 通过 三 次 握手 建立 TCP 连 接 ， 这 时 客户 端 将 会 建立 连 
接 失 败 。 


.fcvbuf=size: 设置 监听 句柄 的 SO_RCVBUF 参 数 。 
sndbuf=size: 设置 监听 句柄 的 SO_SNDBUF 参 数 。 
` accept_filter: 设置 accept 过 滤器 ， 只 对 FreeBSD 操 作 系 统 有 用 。 


* deferred: 在 设置 该 参数 后 ， 若 用 户 发 起 建立 连接 请 求 ， 并 且 完 
成 了 TCP 的 三 次 握手 ， 内 核 也 不 会 为 了 这 次 的 连接 调度 worker 进 程 来 处 
理 ， 只 有 用 户 真 的 发 送 请 求 数 据 时 (内核 已 经 在 网 卡 中 收 到 请 求 数据 
包 ) ， 内 核 才 会 唤醒 wotket 进 程 处 理 这 个 连接 。 这 个 参数 适用 于 大 并 发 
的 情况 下 ， 它 减轻 了 wotket 进 程 的 负担 。 当 请 求 数据 来 临时 ，wotket 进 
程 才 会 开始 处 理 这 个 连接 。 只 有 确认 上 面 所 说 的 应 用 场景 符合 自己 的 业 

务 需求 时 ， 才 可 以 使 用 deferred 配 置 。 


. bind: 绑 定 当前 端口 /地 址 对 ， 如 127.0.0.1:8000。 只 有 同时 对 一 个 
端口 监听 多 个 地 址 时 才 会 生效 。 


. SS]: 在 当前 监听 的 端口 上 建立 的 连接 必须 基于 SSL 协 议 。 
(2) 主机 名 称 


语法 : server_name name[...]; 


I 
3 


默认 : server name 
配置 块 : server 


server_name 后 可 以 跟 多 个 主机 名 称 ， 如 server_name 


www.testweb.com 、 download.testweb.com:;。 


在 开始 处 理 一 个 HTTP 请 求 时 ，Nginx 会 取出 header 头 中 的 Host， 与 
每 个 server 中 的 server_name 进 行 匹 配 ， 以 此 决定 到 底 由 哪 一 个 server 抉 来 
处 理 这 个 请 求 。 有 可 能 一 个 Host 与 多 个 server 块 中 的 server_name 都 匹 
配 ， 这 时 就 会 根据 匹配 优先 级 来 选择 实际 处 理 的 server 块 。server_name 
与 Host 的 匹配 优先 级 如 下 : 


1) 首先 选择 所 有 字符 串 完 全 匹配 的 server_name， 如 


www.testweb.com 。 
2) 其 次 选择 通配符 在 前 面 的 server_name， 如 *.testweb.com。 


3) 再 次 选择 通配符 在 后 面 的 server_name， 如 www.testweb.* 。 


4) 最 后 选择 使 用 正则 表达 式 才 匹配 的 server_name， 如 


~A\testweb\.comy$。 


实际 上 ， 这 个 规则 正 是 7.7 节 中 介绍 的 带 通 配 符 散 列表 的 实现 依 
据 ， 同 时 ， 在 10.4 节 也 介绍 了 虚拟 主机 配置 的 管理 。 如 果 Host 与 所 有 的 
Server_name 都 不 匹配 ， 这 时 将 会 按 下 列 顺序 选择 处 理 的 server 块 。 


1) 优先 选择 在 listen 配 置 项 后 加 入 [defaultldefault_server] 的 server 
块 。 


2) 找到 匹配 listen 端 口 的 第 一 个 server 块 。 


如 果 server_name 后 跟着 空 字符 串 (如 server_name"";) ， 那 么 表示 
匹配 没有 Host 这 个 HTTP 头 部 的 请 求 。 


@ 注意 Nginx 正 是 使 用 setvet_hame 配 置 项 针对 特定 Host 域 名 的 请 
求 提供 不 同 的 服务 ， 以 此 实现 虚拟 主机 功能 。 


(3) server names hash bucket size 
语法 : server_names_hash_bucket_size size: 
默认 : server_names_hash_ bucket_size 32|64|128; 


配置 块 : http、server、location 


为 了 提高 快速 寻找 到 相应 server name 的 能 力 ，Nginx 使 用 散 列 表 来 
存储 server name。 server_names_hash_bucket_size 设 置 了 每 个 散 列 桶 占用 
的 内 存 大 小 。 


(4) server names hash max size 
语法 : server_names_hash_max size size; 
时 认 : server names hash max_ size 512; 
配置 块 : http、server、location 


server_names_hash_max_size 会 影响 散 列 表 的 冲突 率 。 
server_names_hash_max_size 越 大 ， 消 耗 的 内 存 就 越 多 ， 但 散 列 key 的 冲 
突 率 则 会 降低 ， 检 索 速 度 也 更 快 。server_names_hash_max_size 越 小 ， 消 
耗 的 内 存 就 越 小 ， 但 散 列 key 的 冲突 率 可 能 增高 。 





(5) 重 定 同 主机 名 称 的 处 理 
语法 : ”server_name_in_redirect on|off; 
办 : server name in redirect on: 


配置 块 : http、server 或 者 location 





该 配置 需要 配合 server_name 使 用 。 在 使 用 on 打开 时 ， 表 示 在 重 定 问 


请 求 时 会 使 用 server_name 里 配置 的 第 一 个 主机 名 代 蔡 原先 请 求 中 的 Host 
头 部 ， 而 使 用 off 关 闭 时 ， 表 示 在 重 定 癌 请 求 时 使 用 请 求 本 身 的 Host 头 


部 。 





(6) location 
语法 : location[=|~|~*| 人 ~|@]/ri{...} 
配置 块 : server 


location 会 尝试 根据 用 户 请 求 中 的 URI 来 匹配 上 面 的 /uri 表 达 式 ， 如 
果 可 以 匹配 ， 就 选择 location{} 块 中 的 配置 来 处 理 用 户 请 求 。 当 然 ，[ 匹 配 
方式 是 多 样 的 ， 下 面 介 绍 location 的 匹配 规则 。 


1) = 表示 把 URI 作 为 字符 串 ， 以 便 与 参数 中 的 uri 做 完全 匹配 。 例 
如 : 


Jocation =/ 
# 只 有 当 用 户 请 求 是 


/时 ， 才 会 使 用 该 


location 下 的 配置 





2) ~ 表示 匹配 URI 时 是 字母 大 小 写 敏 感 的 。 


3) ~* 表 示 匹 配 URI 时 忽略 字母 大 小 写 问 题 。 


4) 人 表示 匹配 URI 时 只 需要 其 前 半 部 分 与 uri 参 数 匹配 即 可 。 例 
如 : 





location 人 ^~ /images/ { 
# 以 


/images/ 开 始 的 请 求 都 会 匹配 上 





5) @ 表 示 仅 用 于 Nginx 服 务 内 部 请 求 之 间 的 重 定 癌 ， 带 有 @ 的 
location 不 直接 处 理 用 户 请 求 。 


当然 ， 在 uri 参 数 里 是 可 以 用 正则 表达 式 的 ， 例 如 : 





location ~* \.(gif|jpgljpeg)$ { 
# 匹配 以 


.gif、 


‘jpg、 


,jpeg 结尾 的 请 求 








注意 ，location 是 有 顺序 的 ， 当 一 个 请 求 有 可 能 匹配 多 个 location 


时 ， 实 际 上 这 个 请 求 会 被 第 一 个 location 处 理 。 


在 以 上 各 种 匹配 方式 中 ， 都 只 能 表达 为 "如 果 匹 配 .… 则 .……”。 如 采 需 
要 表达 “如 果 不 匹 配 .… 则 .…”， 就 很 难 直 接 做 到 。 有 一 种 解决 方法 是 在 最 
后 一 个 location 中 使 用 /作为 参数 ， 它 会 匹配 所 有 的 HITP 请 求 ， 这 样 就 可 
以 表示 如 果 不 能 匹配 前 面 的 所 有 1location， 则 由 “/ 这 个 location 处 理 。 例 
如 : 





location / 
# /可 以 匹配 所 有 请 求 





2.4.2 ”文件 路 径 的 定义 


下 面 介绍 一 下 文件 路 径 的 定义 配置 项 。 


(1) groot 方 式 设置 资源 路 径 


语法 : root path; 


驮 认 : root html; 
配置 块 : http、server、location、if 


例如 ， 定 义 资 源 文件 相对 于 HTTP 请 求 的 根 目录 。 





location /download/ { 
root /opt/web/html1/; 
} 





在 上 面 的 配置 中 ， 如 果 有 一 个 请 求 的 URI 


是 /download/index/test.html， 那 么 Web 服 务 器 将 会 返回 服务 器 





上 /opt/web/html/download/index/test.html 文 件 的 内 容 。 
(2) 以 alias 方 式 设置 资源 路 符 
语法 : alias path; 


配置 块 location 





alias 也 是 用 来 设置 文件 资源 路 径 的 ， 它 与 root 的 不 同 点 主要 在 于 如 
何 解 读 紧 跟 location 后 面 的 uri 参 数 ， 这 将 会 致使 alias 与 root 以 不 同 的 方式 
将 用 户 请 求 映射 到 真正 的 磁盘 文件 上 。 例 如 ， 如 果 有 一 个 请 求 的 URI 
是 /conf/nginx.conf， 而 用 户 实际 想 访问 的 文件 
在 /usr/local/nginx/conf/nginx.conf， 那 么 想 要 使 用 alias 来 进行 设置 的 话 ， 
可 以 采用 如 下 方式 : 





location /conf { 
alias /usr/local/nginx/conf/; 
} 





如 果 用 root 设 置 ， 那 么 语句 如 下 所 示 : 





Jocation /conf { 
root /usr/local/nginx/; 
} 








使 用 alias 时 ， 在 URI 疝 实际 文件 路 径 的 映射 过 程 中 ， 已 经 把 location 
后 配置 的 /conf 这 部 分 字符 串 丢 弃 挥 ， 因 此 ，/conf/nginx.conf 请 求 将 根据 
alias path 映 射 为 path/nginx.conf。root 则 不 然 ， 它 会 根据 完整 的 URI 请 求 
来 映射 ， 因 此 ，/conf/nginx.conf 请 求 会 根据 root path 映 射 为 
path/conf/nginx.conf。 这 也 是 root 可 以 放置 到 http、server、location 或 if 块 
中 ， 而 alias 只 能 放置 到 location 块 中 的 原因 。 


alias 后 面 还 可 以 添加 正则 表达 式 ， 例 如 : 





location ~ ^/test/(\w+)\.(\w+)$ { 
alias /usr/local/nginx/$2/$1.$2; 
} 





这 样 ， 请 求 在 访问 /test/nginx.conf 时 ，Nginx 会 返 
回 /usr/local/nginx/conf/nginx.conf 文 件 中 的 内 容 。 


(3) 访问 首页 


语法 : index file...: 


RR 认 : index index.html: 
配置 块 : http、server、location 


有 时 ， 访 问 站 点 时 的 URI 是 /， 这 时 一 般 是 返回 网 站 的 首页 ， 而 这 与 
root 和 和 alias 都 不 同 。 这 里 用 ngx_http_index_module 模 块 提供 的 index 配 置 
实现 。index 后 可 以 跟 多 个 文件 参数 ，Nginx 将 会 按照 顺序 来 访问 这 些 文 
件 ， 例 如 : 





Jocation / { 

root path,; 

index /index. html /html/index.php /index.php; 
} 





接收 到 请 求 后 ， i 如 果 可 
以 访问 ， 就 直接 返回 文件 内 容 结束 请 求 ， 否 则 再 试图 返 
path/html/index.php 文 件 的 内 容 ， 依 此 类 推 。 





(4) 根据 HTTP 返 回 码 重 定向 页 面 
语法 : ”error_page code[code...][=|=answer-code]uril@named_location 
配置 块 : http、server、location、if 


当 对 于 某 个 请 求 返 回 错误 码 时 ， 如 果 匹 配 上 了 error_ page 中 设置 的 
code， 则 重 定 同 到 新 的 URI 中 。 例 如 : 








error_page 404 /404.html; 


error_page 502 503 504 /50x.html; 
error_page 403 http://example.com/forbidden.html 


/ 
error_page 404 = @fetch; 








注意 ， 昌 然 重 定向 了 URI， 但 返回 的 HTTP 错 误 码 还 是 与 原来 的 相 
同 。 用 户 可 以 通过 “=” 来 更 改 返 回 的 错误 码 ， 例 如 : 





error_page 404 =200 /empty .gif; 
error_page 404 =403 /forbidden.gif; 











也 可 以 不 指定 确切 的 返回 错误 码 ， 而 是 由 重 定 癌 后 实际 处 理 的 真实 
结果 来 决定 ， 这 时 ， 只 要 把 “=” 后 面 的 错误 码 去 挥 即 可 ， 例 如 : 








error_page 404 = /empty.gif; 





如 果 不 想 修改 URI， 只 是 想 让 这 样 的 请 求 重 定 同 到 男 一 个 location 中 
进行 处 理 ， 那 么 可 以 这 样 设置 : 





Jocation / ( 
error_page 404 @fallback; 


) 
lJocation @fallback ( 
proxy_pass http://backend 





这 样 ， 返 回 404 的 请 求 会 被 反 同 代理 到 http://backend 上 游 服 务 器 中 
处 理 。 


(5) 是否 允 许 递 归 使 用 error_page 
语法 : ”recursive_error_pages[on|off]; 
默认 : recursive_error_pages off; 
配置 块 : http、server、location 
确定 是 否 允 许 递 归 地 定义 error_page。 

(6) try_files 
语法 : try_files path1[path2]uri; 
配置 块 : server、location 


try_files 后 要 跟 若 干 路 径 ， 如 pathl path2...， 而 且 最 后 必须 要 有 uri 参 
数 ， 意 义 如 下 : 答 试 按照 顺序 访问 每 一 个 path， 如 果 可 以 有 效 地 读 取 ， 
就 直接 向 用 户 返 回 这 个 path 对 应 的 文件 结束 请 求 ， 否 则 继续 同 下 访问 。 
如 果 所 有 的 path 都 找 不 到 有 效 的 文件 ， 就 重 定 同 到 最 后 的 参数 uri 上 。 
此 ， 最 后 这 个 参数 uri 必 须 存在 ， 而 且 它 应 该 是 可 以 有 效 重 定向 的 。 例 
如 : 














try_files /system/maintenance.htm] $uri $uri/index.html $uri.html @other; 
Jocation @other { 
proxy_pass http://backend 


上 上面 这 段 代码 表示 如 果 前 面 的 路 径 ， 如 /system/maintenance.html 
等 ， 都 找 不 到 ， 就 会 反问 代理 到 http://backend 服务 上 。 还 可 以 用 指定 错 
误 码 的 方式 与 error_page 配 合 使 用 ， 例 如 : 





location / 
try_files $uri $uri/ /error.phpc=404 =404; 
} 





2.4.3 ”内 存 及 磁盘 资源 的 分 配 


下 面 介绍 处 理 请 求 时 内 存 、 磁 盘 资 源 分 配 的 配置 项 。 
(1) HITP 包 体 只 存储 到 磁盘 文件 中 

语法 : dlient_body_in_file_only on|cleanloff; 

默认 : client_body_in_file_only off; 


配置 块 : http、server、location 





当 值 为 非 off 时 ， 用 户 请 求 中 的 HITP 包 体 一 律 存 储 到 磁盘 文件 中 ， 
即使 只 有 0 字 市 也 会 存储 为 文件 。 当 请 求 结束 时 ， 如 果 配 置 为 on"， 则 这 
个 文件 不 会 被 删除 〈 该 配置 一 般 用 于 调试 、 定 位 问题 ) ， 但 如 果 配 置 为 


clean， 则 会 删除 该 文件 。 


(2) HTTP 包 体 尽 量 写 入 到 一 个 内 存 buffer 中 


语法 : client body_in_single_buffer onloff; 
默认 :client _ body_in_single_buffer off; 
配置 块 : http、server、location 


用 户 请 求 中 的 HITP 包 体 一 律 存 储 到 内 存 buffer 中 。 当 然 ， 如 采 
HTTP 包 体 的 大 小 超过 了 下 面 client_body_buffer_size 设 置 的 值 ， 包 体 还 
是 会 号 入 到 磁盘 文件 中 。 


(3) 存储 HTTP 头 部 的 内 存 buffer 大 小 
语法 :client header_ buffer size size; 
驮 认 : client header buffer size 1k: 
配置 块 : http、server 


上 面 配 置 项 定义 了 正常 情况 下 Nginx 接 收 用 户 请 求 中 HTTP header 剖 
分 (包括 HTTP 行 和 HTTP 头 部 ) 时 分 配 的 内 存 buffer 大 小 。 有 了 时， 请 求 
中 的 HTTP header 部 分 可 能 会 超过 这 个 大 小 ， 这 时 


large_client_header_buffers 定 义 的 buffer 将 会 生效 。 
(4) 存储 超大 HITP 头 部 的 内 存 buffer 大 小 


语法 : large_client_header_buffers number size; 


默认 :_ large_client_header_buffers 48k; 
配置 块 : http、server 


large_client_header_buffers 定 义 了 Nginx 接 收 一 个 超大 HTTP 头 部 请 
求 的 buffer 个 数 和 每 个 buffer 的 大 小 。 如 果 HTTP 请 求 行 (如 GETVindex 
HTTP/1.1〉 的 大 小 超过 上 面 的 单个 buffer， 则 返回 "Request URI too 
large"(414)。 请 求 中 一 般 会 有 许多 header， 每 一 个 header 的 大 小 也 不 能 超 
过 单个 buffer 的 大 小 ， 和 否则 会 返回 "Bad request"(400)。 当 然 ， 请 求 行 和 请 
求 头 部 的 总 和 也 不 可 以 超过 buffer 个 数 *buffer 大 小 。 





(5) 存储 HTTP 包 体 的 内 存 buffer 大 小 
语法 : dlient_body_buffer_size size; 
默认 :client_body_buffer_size 8k/16k; 
配置 块 : http、server、location 


上 面 配置 项 定义 了 Nginx 接 收 HTTP 包 体 的 内 存 缓冲 区 大 小 。 也 就 是 
说 ，HTTP 包 体会 先 接 收 到 指定 的 这 块 缓存 中 ， 之 后 才 决 定 是 否 写 入 侯 
舱 - 


To 





@ 注意 ”如果 用 户 请 求 中 含有 HTTP 头 部 Content-Length， 并 且 其 
标识 的 长 度 小 于 定义 的 buffer 大 小 ， 那 么 Nginx 会 自动 降低 本 次 请 求 所 使 


用 的 内 存 buffer， 以 降低 内 存 消耗 。 
(6) HTTP 包 体 的 临时 存放 目录 
语法 : client_body_temp_path dir-path[levell[level2[level3]]] 
默认 : client_body_temp_path client_body_temp; 


配置 块 : http、server、location 





上 面 配置 项 定义 HITP 包 体 存 放 的 临时 目录 。 在 接收 HTTP 包 体 时 ， 
如 果 包 体 的 大 小 大 于 client_body_buffer_size， 则 会 以 一 个 递增 的 整数 命 
名 并 存放 到 client_body_temp_path 指 定 的 目录 中 。 后 面 跟着 的 level1、 
level2、level3， 是 为 了 防止 一 个 目录 下 的 文件 数量 太 多 ， 从 而 导致 性 能 
下 降 ， 因 此 使 用 了 level 参 数 ， 这 样 可 以 按照 临时 文件 名 最 多 再 加 三 层 
录 。 例 如 : 





I 





client_ body_ temp_ path /opt/nginx/client temp 1 2; 








如 果 新 上 传 的 HTTP 包 体 使 用 00000123456 作 为 临时 文件 名 ， 就 会 被 
存放 在 这 个 目录 中 。 





/opt/nginx/client_temp/6/45/00000123456 





(7) connection pool size 


语法 : connection_pool_size size; 
默认 : connection_pool_size 256; 
配置 块 : http、server 


Nginx 对 于 每 个 建立 成 功 的 TCP 连 接 会 预先 分 配 一 个 内 存 池 ， 上 面 
的 size 配 置 项 将 指定 这 个 内 存 池 的 初始 大 小 〈 即 ngx_connection_t 结 构 体 
中 的 pool 内 存 池 初始 大 小 ，9.8.1 节 将 介绍 这 个 内 存 池 是 何 时 分 配 的 ) ， 
用 于 减少 内 核对 于 小 块 内 存 的 分 配 次 数 。 需 层 重 设置 ， 因 为 更 大 的 size 
会 使 服务 器 消耗 的 内 存 增 多 ， 而 更 小 的 Size 则 会 引发 更 多 的 内 存 分 配 次 
数 。 





(8) request_pool_size 
语法 : ”request_pool_size size; 
默认 :request_pool_size 4k; 
配置 块 : http、server 


Nginx 开 始 处 理 HITP 请 求 时 ， 将 会 为 每 个 请 求 都 分 配 一 个 内 存 池 ， 
Size 配置 项 将 指定 这 个 内 存 池 的 初始 大 小 《〈 即 ngx_http_request_t 结 构 体 
中 的 pool 内 存 池 初 始 大 小 ，11.3 节 将 介绍 这 个 内 存 池 是 何 时 分 配 的 ) ， 
用 于 减少 内 核对 于 小 块 内 存 的 分 配 次 数 。TCP 连 接 关 闭 时 会 销毁 


connection_pool_size 指 定 的 连接 内 存 池 ，HTTP 请 求 结 束 时 会 销毁 
request_pool_size 指 定 的 HITP 请 求 内 存 池 ， 但 它们 的 创建 、 销 毁 时 间 并 
不 一 致 ， 因 为 一 个 TCP 连 接 可 能 被 复 用 于 多 个 HTTP 请 求 。8.7 市 会 详 述 
内 存 池 原 理 。 


2.4.4 网 络 连接 的 设置 


下 面 介 绍 网 络 连 接 的 设置 配置 项 。 
(1) 读 取 HTTP 头 部 的 超时 时 间 
语法 : client_header timeout time 〈 默 认 单 位 : 秒 ) ; 
驮 认 :_ client header _timeout 60; 


配置 块 : http、server、location 





客户 端 与 服务 器 建立 连接 后 将 开始 接收 HTTP 头 部 ， 在 这 个 过 程 
， 如 果 在 一 个 时 间 间 隔 (超时 时 间 〉 内 没有 读 取 到 客户 端 发 来 的 字 
， 则 认为 超时 ， 并 回 客 户 端 返 回 408("Request timed out") 啊 应 。 





寺 于 


(2) 读 取 HTTP 包 体 的 超时 时 间 


语法 : client_body_timeout time (默认 单位 : 秒 ) ; 


默认 :client_body_timeonut 60; 
配置 块 : http、server、location 


此 配置 项 与 client_header_timeout 相 似 ， 只 是 这 个 超时 时 间 只 在 读 取 
HTTP 包 体 时 才 有 效 。 


(3) 发 送 啊 应 的 超时 时 间 
语法 : send_timeout time， 
驮 认 : send_timeout 60; 
配置 块 : http、server、location 


这 个 超时 时 间 是 发 送 啊 应 的 超时 时 间 ， 即 Nginx 服 务 器 向 客户 端 发 
送 了 数据 包 ， 但 客户 端 一 直 没 有 去 接收 这 个 数据 包 。 如 果 某 个 连接 超过 
send_timeout 定 义 的 超时 时 间 ， 那 么 Nginx 将 会 关闭 这 个 连接 。 








(4) reset timeout connection 
语法 : reset_timeout_connection onloff; 
驮 认 : reset_timeout_connection off: 


配置 块 : http、server、location 


连接 超时 后 将 通过 向 客户 端 发 送 RST 包 来 直接 重 置 连接 。 这 个 选项 
打开 后 ，Nginx 会 在 某 个 连接 超时 后 ， 不 是 使 用 正常 情形 下 的 四 次 握手 
关闭 TCP 连 接 ， 而 是 直接 向 用 户 发 送 RST 重 置 包 ， 不 再 等 待 用 户 的 应 
答 ， 直 接 释 放 Nginx 服 务 器 上 关于 这 个 套 接 字 使 用 的 所 有 绥 存 (如 TCP 
滑动 窗口 ) 。 相 比 正常 的 关闭 方式 ， 它 使 得 服务 器 避免 产生 许多 处 于 
FIN_WAIT_1、FIN_WAIT_2、TIME_WAIT 状 态 的 TCP 连 接 。 








注意 ， 使 用 RST 重 置 包 关 闭 连接 会 融 来 一 些 问 题 ， 默 认 情 况 下 不 会 
开启 。 


(5) lingering_close 
语法 : lingering_close offlonlalways; 
默认 : lingering_close on; 


配置 块 : http、server、location 





该 配置 控制 Nginx 关 闭 用 户 连 接 的 方式 。always 表 示 关 闭 用 户 连 接 
前 必须 无 条 件 地 处 理 连接 上 所 有 用 户 发 送 的 数据 。off 表 示 关 闭 连 接 时 完 
全 不 管 连接 上 是 否 已 经 有 准备 就 绪 的 来 自用 户 的 数据 。on 是 中 间 值 ， 一 
般 情况 下 在 关闭 连接 前 都 会 处 理 连接 上 的 用 户 发 送 的 数据 ， 除 了 有 些 情 
况 下 在 业务 上 认定 这 之 后 的 数据 是 不 必要 的 。 


(6) lingering_time 


语法 : lingering_time time; 
默认 : lingering_time 30s; 
配置 块 : http、server、location 


lingering_close 启 用 后 ， 这 个 配置 项 对 于 上 传 大 文件 很 有 用 。 上 文 讲 
过 ， 当 用 户 请 求 的 Content-Length 大 于 max_client_body_size 配 置 时 ， 
Nginx 服 务 会 立刻 向 用 户 发 送 413 (Request entity too large) 响应 。 但 
是 ， 很 多 客户 端 可 能 不 管 413 返 回 值 ， 仍 然 持续 不 断 地 上 传 HITP 
body， 这 时 ， 经 过 了 lingering time 设置 的 时 间 后 ，Nginx 将 不 管用 户 是 
个 仍 在 上 传 ， 都 会 把 连接 关闭 掉 。 





(7) lingering timeout 
语法 : lingering_timeout time; 
默认 : lingering_timeout 5s; 


配置 块 : http、server、location 





lingering_close 生 效 后 ， 在 关闭 连接 前 ， 会 检测 是 否 有 用 户 发 送 的 数 
据 到 达 服 务 器 ， 如 果 超 过 lingering_timeout 时 间 后 还 没有 数据 可 读 ， 就 直 
接 关 闭 连 接 ; 否则 ， 必 须 在 读 取 完 连接 缓冲 区 上 的 数据 并 丢弃 掉 后 才 会 
关闭 连接 。 





(8) 对 某 些 浏览 器 禁用 keepalive 功 能 
语法 : keepalive_disable[msie6|safarilnone]... 
于 认 : keepalive_disablemsie6 safari 
配置 块 : http、server、location 


HTTP 请 求 中 的 keepalive 功 能 是 为 了 让 多 个 请 求 复 用 一 个 HITP 长 连 
接 ， 这 个 功能 对 服务 器 的 性 能 提高 是 很 有 帮助 的 。 但 有 些 浏览 器 ， 如 下 
6 和 Safari， 它 们 对 于 使 用 keepalive 功 能 的 POST 请 求 处 理 有 功能 性 问题 。 
因此 ， 针 对 IE 6 及 其 早期 版 本 、Safari 浏 览 器 默认 是 禁用 keepalive 功 能 
的 。 


(9) keepalive 超 时 时 间 
语法 : keepalive_timeout time (默认 单位 : 秒 ) ; 
时 认 : keepalive_timeout 75; 


配置 块 : http、server、location 


一 个 keepalive 连 接 在 闲置 超过 一 定时 间 后 《默认 的 是 75 秒 ) ， 服 务 
器 和 浏览 器 都 会 去 关闭 这 个 连接 。 当 然 ，keepalive_timeout 配 置 项 是 用 
来 约束 Nginx 服 务 器 的 ，Nginx 也 会 按照 规范 把 这 个 时 间 传 给 浏览 器 ， 但 
每 个 浏览 器 对 待 keepalive 的 策略 有 可 能 是 不 同 的 。 





(10) 一 个 keepalive 长 连接 上 人 允许 承载 的 请 求 最 大 数 

语法 : keepalive_requests ni 

天 认 : keepalive_requests 100; 

配置 块 : http、server、location 

一 个 keepalive 连 接 上 默认 最 多 只 能 发 送 100 个 请 求 。 
(11) tcp_nodelay 

语法 : tcp_nodelay onloff; 

默认 : tcp_nodelay on; 

配置 块 : http、server、location 

确定 对 keepalive 连 接 是 否 使 用 TCP_NODELAY 选 项 。 
(12) tcp_nopush 

语法 : tcp_nopush onloff; 

默认 : tcp_nopush off; 


配置 块 : http、server、location 


在 打开 sendfile 选 项 时 ， 确 定 是 否 开 局 FreeBSD 系 统 上 的 
TCP_NOPUSH 或 Linux 系 统 上 的 TCP_CORK 功 能 。 打 开 tcp_nopush 后 ， 
将 会 在 发 送 啊 应 时 把 整个 啊 应 包头 放 到 一 个 TCP 包 中 发 送 。 


2.4.5 MIME 类 型 的 设置 


下 面 是 MIME 类 型 的 设置 配置 项 。 
* MIME type 与 文件 扩展 的 映射 
语法 : typet{..…}; 

配置 块 : http、server、location 


定义 MIME type 到 文件 扩展 名 的 映射 。 多 个 扩展 名 可 以 映射 到 同一 


个 MIME type。 例 如 : 





types { 
text/html html; 
text/html conf; 
image/gif gif; 
image/jpeg jpg; 





: 默认 MIME type 


语法 : default_type MIME-type; 


默认 :default_type text/plain; 


配置 块 : http、server、location 








当 找 不 到 相应 的 MIME type 与 文件 扩展 名 之 间 的 映射 时 ， 使 用 默认 
的 MIME type 作 为 HTTP header 中 的 Content-Type。 


“ types_hash_bucket_size 
语法 : types_hash_bucket_size size; 
默认 : types_hash_bucket_size 32|64|128; 
配置 块 : http、server、location 


为 了 快速 寻找 到 相应 MIME type，Nginx 使 用 散 列 表 来 存储 MIME 
type 与 文件 扩展 名 。types_hash_bucket_size 设 置 了 每 个 散 列 桶 占用 的 内 
存 大 小 。 





“ types_hash_ max_size 

语法 : types_hash_max_size size; 
默认 : types_hash_max_size 1024; 
配置 块 : http、server、location 


types_hash_max_size 影 响 散 列表 的 冲突 率 。types_hash_max_size 越 
大 ， 就 会 消耗 更 多 的 内 存 ， 但 散 列 key 的 冲突 率 会 降低 ， 检 过 速度 就 更 


快 。types_hash_max_size 越 小 ， 消 耗 的 内 存 就 越 小 ， 但 散 列 key 的 冲突 率 


2.4.6 ”对 客户 端 请 求 的 限制 
下 面 介绍 对 客户 端 请 求 的 限制 的 配置 项 。 
(1) 按 HTTP 方 法 名 限制 用 户 请 求 
语法 : ”limit_except method...{...} 


配置 块 : location 





Nginx 通 过 limit except 后 面 指 定 的 方法 名 来 限制 用 户 请 求 。 方 法 名 
可 取 值 包括 : GET、HEAD、POST、PUT、DELETE、MKCOL、 
COPY、 MOVE、 OPTIONS、 PROPFIND、 PROPPATCH、 LOCK.、 


UNLOCK 或 者 PATCH。 例 如 : 





Jimit_except GET { 
allow 192.168.1.0/32,; 
deny all; 

} 








注意 ， 人 允许 GET 方 法 就 意味 着 也 允许 HEAD 方 法 。 因 此 ， 上 面 这 段 
代码 表示 的 是 禁止 GET 方 法 和 HEAD 方 法 ， 但 其 他 HTTP 方 法 是 允许 
的 。 


(2) HITP 请 求 包 体 的 最 大 值 
语法 : client_max_body_size size; 
默认 : client_max_body_size 1m; 
配置 块 : http、server、location 


浏览 器 在 发 送 含 有 较 大 HITP 包 体 的 请 求 时 ， 其 头 部 会 有 一 个 
Content-Length 字 段 ，client_max_body_size 是 用 来 限制 Content-Length 所 
示 值 的 大 小 的 。 因 此 ， 这 个 限制 包 体 的 配置 非常 有 用 处 ， 因 为 不 用 等 
Nginx 接 收 完 所 有 的 HITP 包 体 一 一 这 有 可 能 消耗 很 长 时 间 一 一 就 可 以 告 
诉 用 户 请 求 过 大 不 被 接受 。 例 如 ， 用 户 试图 上 传 一 个 10GB 的 文件 ， 
Nginx 在 收 完 包头 后 ， 发 现 Content-Length 超 过 client_max_body_size 定 义 
的 值 ， 就 直接 发 送 413("Request Entity Too Large") 响 应 给 客户 端 。 








(3) 对 请 求 的 限 速 
语法 : limit_rate speed; 
默认 : limit_rate 0; 
配置 块 : http、server、location、if 


此 配置 是 对 客户 端 请 求 限制 每 秒 传输 的 字 市 数 。speed 可 以 使 用 
2.2.4 节 中 提 到 的 多 种 单位 ， 黑 认 参 数 为 0， 表 示 不 限 速 。 


针对 不 同 的 客户 端 ， 可 以 用 $limit_rate 参 数 执行 不 同 的 限 速 策略 。 
例如 : 





server { 
if ($slow) { 
set $limit_rate 4k; 
} 


} 





(4) limit rate_after 
语法 : limit_rate_after time:;: 
于 R 认 : limit_rate_after 1m: 
配置 块 : http、server、location、if 


此 配置 表示 Nginx 回 客户 端 发 送 的 响应 长 度 超 过 limit_rate_after 后 才 
开始 限 速 。 例 如 : 





limit_rate after 1m， 
limit_rate 100k; 





11.9.2 节 将 从 源码 上 介绍 limit_rate_after 与 limit_rate 的 区 别 ， 以 及 
HTTP 框 架 是 如 何 使 用 它们 来 限制 发 送 啊 应 速度 的 。 


2.4.7 文件 操作 的 优化 


下 面 介绍 文件 操作 的 优化 配置 项 。 
(1) sendfile 系 统 调用 

语法 : sendfile onloff; 

默认 : sendfile off: 

配置 块 : http、server、location 


可 以 局 用 Linux 上 的 sendfile 系 统 调用 来 发 送 文件 ， 它 减少 了 内 核 态 
与 用 户 态 之 间 的 两 次 内 存 复制 ， 这 样 就 会 从 磁盘 中 读 取 文件 后 直接 在 内 
核 态 发 送 到 网 卡 设 备 ， 提 高 了 及 送 文件 的 效率 。 


2) AIO 系 统 调用 
语法 : aio onloff; 
默认 : aio off; 
配置 块 : http、server、location 


此 配置 项 表示 是 否 在 FreeBSD 或 Linux 系 统 上 启用 内 核 级 别 的 异步 文 
件 IO 功 能 。 注 意 ， 它 与 sendfile 功 能 是 互 斥 的 。 


(3) directio 


语法 : directio sizeloff; 
于 认 : directio off:; 
配置 块 : http、server、location 


此 配置 项 在 FreeBSD 和 Linux 系 统 上 使 用 O_DIRECT 选 项 去 读 取 文 
件 ， 缓 冲 区 大 小 为 size， 通 常 对 大 文件 的 读 取 速度 有 优化 作用 。 注 意 ， 
它 与 sendfile 功 能 是 互 斥 的 。 


(4) directio alignment 
语法 : directio_alignment size; 
默认 : directio_alignment 512; 


配置 块 : http、server、location 





它 与 directio 配 合 使 用 ， 指 定 以 directio 方 式 读 取 文件 时 的 对 齐 方式 。 
一 般 情 况 下 ，512B 已 经 足够 了 ， 但 针对 一 些 高 性 能 文件 系统 ， 如 Linux 
下 的 XFS 文 件 系统 ， 可 能 需要 设置 到 4KB 作 为 对 齐 方式 。 





(5) 打开 文件 缓存 
语法 : open_file_cache max=N[inactive=time]|off; 


中 认 : open_file_cache off; 


配置 块 : http、server、location 
文件 绥 存 会 在 内 存 中 存储 以 下 3 种 信息 : 
` 文件 句柄 、 文 件 大 小 和 上 次 修改 时 间 。 





主 自 、 
已 Jo 


` 已 经 打开 过 的 目录 结构 。 
没有 找到 的 或 者 没有 权限 操作 的 文件 人 
这 样 ， 通 过 读 取 缓存 就 减少 了 对 人 破 盘 的 操作 。 
. max: 表示 在 内 存 中 存储 元 素 的 最 大 个 数 。 当 达到 最 大 限制 数量 
将 会 


该 配置 项 后 面 跟 3 种 参数 。 
后 ， 将 采用 LRU (Least Recently Used) 算法 从 缓存 中 淘汰 最 近 最 少 使 用 


的 元 素 。 
.inactive: 表示 在 inactive 指 定 的 时 间 段 内 没有 被 访问 过 的 元 素 】 


被 淘汰 。 默 认 时 间 为 60 秒 。 
off: 关闭 缓存 功能 。 





例如 : 
open_file_cache max=1000 inactive=20s,; 





(6) 是 否 缓存 打开 文件 错误 的 信息 
语法 : ”open_file_cache_errors on|off; 
默认 : open file_cache_errors off; 


配置 块 : http、server、location 





此 配置 项 表示 是 否 在 文件 缓存 中 缓存 打开 文件 时 出 现 的 找 不 到 路 


径 、 没 有 权限 等 错误 信息 。 
(7) 不 被 淘汰 的 最 小 访问 次 数 
语法 : open_file_cache_min_uses number; 
四 认 : open_file_cache_min_uses 1; 
配置 块 : http、server、location 


它 与 open_file_cache 中 的 inactive 参 数 配 合 使 用 。 如 果 在 inactive 指 定 
的 时 间 段 内 ， 访 问 次 数 超过 了 open_file_cache_min_uses 指 定 的 最 小 次 
数 ， 那 么 将 不 会 被 淘汰 出 缓存 。 


(8) 检验 缓存 中 元 素 有 效 性 的 频率 


语法 : open_file_cache_valid time; 


默认 : open_file_cache_valid 60s; 


配置 块 : http、server、location 








默认 为 每 60 秒 检查 一 次 缓存 中 的 元 素 是 合 仍 有 效 。 


2.4.8 对 客户 端 请 求 的 特殊 处 理 








下 面 介绍 对 客户 端 请 求 的 特殊 处 理 的 配置 项 。 
(1) 忽略 不 合法 的 HTTP 头 部 

语法 : ignore_invalid_headers onloff; 

默认 : ignore_invalid_headers on; 

配置 块 : http、server 


如 果 将 其 设置 为 off， 那 么 当 出 现 不 合法 的 HTTP 头 部 时 ，Nginx 会 拒 
绝 服 务 ， 并 直接 向 用 户 发 送 400 (Bad Request) 错误 。 如 果 将 其 设置 为 
on， 则 会 包 略 此 HTTP 头 部 。 


(2) HTTP 头 部 是 否 允 许 下 划 线 


语法 : underscores_in_headers on|off; 


驮 认 :， underscores_in_headers off; 

配置 块 : http、server 

默认 为 off， 表 示 HTTP 头 部 的 名 称 中 不 允许 带 * ”( 下 划 线 ) 。 
(3) 对 If-Modified-Since 头 部 的 处 理 策 略 

语法 : if_modified_since[offlexactlbeforel]; 

办: if_modified since exact:; 

配置 块 : http、server、location 


出 于 性 能 考虑 ，Web 浏 览 器 一 般 会 在 客 尸 端 本 地 绥 存 一 些 文 件 ， 并 


存储 当时 获取 的 时 间 。 这 样 ， 下 次 同 Web 服 务 器 获取 缓存 过 的 资源 时 ， 
束 可 以 用 Hf-Modified-Since 尖 部 把 上 次 获取 的 时 间 朱 带 上 ， 而 
计 modified_since 将 根据 后 面 的 参数 决定 如 何 处 理 If-Modified-Since 头 


相关 参数 说 明 如 下 。 


. off: 表示 忽略 用 户 请 求 中 的 IEModified_-Since 头 部 。 这 时 ， 如 果 获 


取 一 个 文件 ， 那 么 会 正常 地 返回 文件 内 容 。HTTP 响 应 码 通常 是 200。 


.exact: 将 If-Modified-Since 头 部 包含 的 时 间 与 将 要 返回 的 文件 上 次 


修改 的 时 间 做 精确 比较 ， 如 果 没 有 匹配 上 ， 则 返回 200 和 文件 的 实际 内 
容 ， 如 果 匹 配 上 ， 则 表示 浏览 器 缓存 的 文件 内 容 已 经 是 最 新 的 了 ， 没 有 
必要 再 返回 文件 从 而 浪费 时 间 与 带宽 了 ， 这 时 会 返回 304 Not Modified ， 
浏览 器 收 到 后 会 直接 读 取 自己 的 本 地 缓存 。 


.befote: 是 比 exact 更 宽松 的 比较 。 只 要 文件 的 上 次 修改 时 间 等 于 
或 者 早 于 用 户 请 求 中 的 If-Modified-Since 头 部 的 时 间 ， 就 会 向 客户 端 返 
304 Not Modified。 


(4) 文件 未 找到 时 是 否 记录 到 error 日 志 
语法 : log_not found onloff; 
默认 : log_not_found on; 
配置 块 : http、server、location 


此 配置 项 表示 当 处 理 用 户 请 求 且 需要 访问 文件 时 ， 如 果 没 有 找到 文 
件 ， 是 否 将 错误 日 志 记 录 到 error.log 文 件 中 。 这 仅 用 于 定位 问题 。 


(5) merge_slashes 
语法 : merge_slashes on|off; 


默认 :merge_slashes on:; 


配置 块 : http、server、location 


此 配置 项 表示 是 否 合并 相 邻 的 “”， 例 如 ，WtestWa.txt， 在 配置 为 on 
时 ， 会 将 其 匹配 为 location/test/a.txt; 如 果 配 置 为 off， 则 不 会 匹配 ，URI 


将 仍然 是 //test///a.txt。 
(6) DNS 解析 地 址 
语法 : ”resolver address..…; 
配置 块 : http、server、location 


设置 DNS 名 字 解 析 服 务 嚣 的 地 址 ， 例 如 : 





resolver 127.0.0.1 192.0.2.1， 





(7) DNS 解析 的 超时 时 间 
语法 : resolver_timeout time:; 
默认 :， resolver_timeout 30s; 
配置 块 : http、server、location 


此 配置 项 表示 DNS 解析 的 超时 时 间 。 





(8) 返回 错误 页 面 时 是 否 在 Server 中 注 明 Nginx 版 本 


语法 : server_tokens onloff; 
四 认 : server_tokens on:; 
配置 块 : http、server、location 


表示 人 处理 请 求 出 错时 是 否 在 啊 应 的 Server 头 部 中 标明 Nginx 版 本 ， 这 
是 为 了 方便 定位 问题 。 


2.4.9 ngx_http_core_module 模 块 提 供 的 变量 


在 记录 access_ log 访 问 日 志文 件 时 ， 可 以 使 用 ngx_http_core_module 
模块 处 理 请 求 时 所 产生 的 丰富 的 变量 ， 当 然 ， 这 些 变量 还 可 以 用 于 其 他 
HTTP 模 块 。 例 如 ， 当 URI 中 的 某 个 参数 满足 设 定 的 条 件 时 ， 有 些 HTTP 
模块 的 配置 项 可 以 使 用 类 似 $arg_PARAMETER 这 样 的 变量 。 又 如 ， 若 
想 把 每 个 请 求 中 的 限 速 信息 记录 到 access 日 志文 件 中 ， 则 可 以 使 用 


$limit _ rate 变量 。 
表 2-1 列 出 了 ngx_http_core_module 模 块 提供 的 这 些 变量 。 


表 2-1 ngx_http_core_module 模 块 提供 的 变量 


参数 名 
$are PARAMETER 
$args 
Sbinary_remote addr 
Sbody bytes sent 
$content length 
$content_ type 
$cookie COOKIE 
$document root 
Suri 


$document uri 


Srequest uri 


$host 


$hostname 


S$http_HEADER 
$sent http HEADER 


$is_ args 


Slimit_rate 
Snginx_version 
$query string 
Sremote addr 
Sremote port 
S$remote_user 
Srequest filename 
Srequest body 
Srequest body file 


$request completion 


Srequest method 
$scheme 


$server addr 


参数 名 
$server_name 
$server_ port 


$server_protocol 


意 义 

HTTP 请 求 中 革 个 参数 的 值 ， 如 /index.html?size=100， 可 以 用 Sare size 下 得 100 这 个 值 

HTTP 请 求 中 的 完整 参数 。 例 如 ， 在 请 求 /index.html? w=120& _h=120 中 ，$args 表示 
字符 串 _w=120&_h=120 

二 进 制 格式 的 客户 端 地 址 。 例 如 : \x0A\xE0B\x0E 

表示 在 向 客户 端 发 送 的 http 响应 中 ， 包 体 部 分 的 字 节 数 

表示 客户 端 请 求 头 部 中 的 Content-Length 字段 

表示 客户 端 请 求 尖 部 中 的 Content-Type 字段 

表示 在 客户 端 请 求 头 部 中 的 cookie 字段 

表示 当前 请 求 所 使 用 的 root 配置 项 的 值 

表示 当前 请 求 的 URI， 不 带 任何 参数 

与 Suri 含义 相同 

表示 客户 端 发 来 的 原始 请 求 URI， 带 完整 的 参数 。$uri 和 Sdocument_uri 未 必 是 用 户 的 
原始 请 求 ， 在 内 部 重 定向 后 可 能 是 重 定向 后 的 URI， 而 $request_uri 永远 不 会 改变 ， 始 终 
是 客户 端的 原始 URI 

表示 客户 玄 请 求 头 部 中 的 Host 字段 。 如果 Host 字段 不 存在 ， 则 以 实际 处 理 的 server 
( 瞳 拟 主机 ) 名 称 代替 : 如 果 Host 字段 中 带 有 端口 ， 如 IP:PORT， 那 么 $host 是 去 掉 端 
口 的 ， 它 的 值 为 IP。$host 是 全 小 写 的 - 这 些 特性 与 http_HEADER 中 的 http_host 不 同 ， 
http_host 只 是 “忠实 ”地 取出 Host 头 部 对 应 的 值 

表示 Nginx 所 在 机 器 的 名 称 。 与 gethostbyname 调用 返回 的 值 相同 

表示 当前 HTTP 请 求 中 相应 头 部 的 值 。HEADER 名 称 全 小写。 例如 ， 用 $http_host 表 
示 请 求 中 Host 尖 部 对 应 的 值 

表示 返回 客户 端的 HTTP 响 应 中 相应 头 部 的 值 。HEADER 名 称 全 小 写 。 
$sent_http_content_type 表示 响应 中 Content-Type 头 部 对 应 的 值 

表示 请 求 中 的 URI 是 否 带 参数 ， 如 果 带 参数 ，Sis_args 值 为 ?， 如 果 不 带 参数 ， 则 是 空 
字符 品 

表示 当前 连接 的 限 速 是 多 少 ，0 表示 无 限 速 

表示 当前 Nginx 的 版 本 号 ， 如 1.0.14 

请 求 URI 中 的 参数 ， 与 $args 相同 ， 然 而 $query_string 是 只 读 的 不 会 改变 

表示 客户 端的 地 扯 

表示 客户 端 连接 使 用 的 端口 

表示 使 用 Auth Basic Module 时 定义 的 用 户 名 

表示 用 户 请 求 中 的 URI 经 过 root 或 alias 转换 后 的 文件 路 径 

表示 HTTP 请 求 中 的 包 体 ， 该 参数 只 在 proxy_pass 或 fastcgi_pass 中 有 意义 

表示 HTTP 请 求 中 的 包 体 存储 的 临时 文件 名 

当 请 求 已 经 全 部 完成 时 ， 其 值 为 “ok "”- 若 没 有 完成 ， 就 要 返回 客户 端 ， 则 其 值 为 空 
字符 囊 ; 或 者 在 断 点 续 传 等 情况 下 使 用 HTTP range 访问 的 并 不 是 文件 的 最 后 一 块 。 那 么 
甚 值 也 是 空 字 符 串 

表示 HTTP 请 求 的 方法 名 ， 如 GET、PUT、POST 等 

表示 HTTP scheme， 如 在 请 求 https;//nginx.com/ 中 表示 https 


例如 ， 用 


表示 服务 器 地 址 
( 续 ) 
意 义 
表示 服务 器 名 称 
表示 服务 器 端口 


表示 服务 器 向 客户 端 发 送 响应 的 协议 ， 如 HITP/1.1 或 HITP/1.0 


2.5 用 HTTP proxy module 配 置 一 个 反 向 代理 服务 


反问 代理 (reverse proxy) 方式 是 指 用 代理 服务 器 来 接受 Internet 上 
的 连接 请 求 ， 然 后 将 请 求 转发 给 内 部 网 络 中 的 上 游 服 务 器 ， 并 将 从 上 游 
服务 器 上 得 到 的 结果 返回 给 Internet 上 请 求 连接 的 客户 端 ， 此 时 代理 服务 
器 对 外 的 表现 就 是 一 个 web 服务 器 。 充 当 反 向 代理 服务 器 也 是 Nginx 的 
一 种 常见 用 法 《〈 反 向 代理 服务 器 必须 能 够 处 理 大 量 并 发 请 求 ) ， 本 节 将 
介绍 Nginx 作 为 HITP 反 加 代理 服务 器 的 基本 用 法 。 














由 于 Nginx 有 具有 “强悍 ”的 高 并 发 高 负载 能 力 ， 因 此 一 般 会 作为 前 端 
的 服务 器 直接 向 客户 端 提供 静态 文件 服务 。 但 也 有 一 些 复杂 、 多 变 的 业 
务 不 适合 放 到 Nginx 服 务 器 上 ， 这 时 会 用 Apache、Tomcat 等 服务 器 来 处 
理 。 于 是 ，Nginx 通 常会 被 配置 为 既是 静态 Web 服 务 器 也 是 反 向 代理 服 
务 器 (如 图 2-3 所 示 ) ， 不 适合 Nginx 处 理 的 请 求 就 会 直接 转发 到 上 游 服 
务 器 中 处 理 。 
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图 2-3 ”作为 静态 Web 服 务 器 与 反 向 代理 服务 器 的 Nginx 


与 Squid 等 其 他 反 向 代理 服务 器 相 比 ，Nginx 的 反 向 代理 功能 有 自己 
的 特点 ， 如 图 2-4 所 示 。 





当 客 户 端 发 来 HTTP 请 求 时 ，Nginx 并 不 会 立刻 转发 到 上 游 服 务 器 ， 
而 是 先 把 用 户 的 请 求 〈 包 括 HITP 包 体 ) 完整 地 接收 到 Nginx 所 在 服务 器 
的 硬盘 或 者 内 存 中 ， 然 后 再 向 上 游 服务 器 及 起 连接 ， 把 缓存 的 客户 并 请 
求 转 及 到 上 游 服务 堪 。 而 Sduid 等 代理 服务 器 则 采用 一 边 接收 客户 端 请 
求 ， 一 边 转发 到 上 游 服务 器 的 方式 。 

Nginx 的 这 种 工作 方式 有 什么 优 缺 点 呢 ? 很 明显 ， 缺 点 是 延长 了 一 


个 请 求 的 处 理 时 间 ， 并 增加 了 用 于 缓存 请 求 内 容 的 内 存 和 磁盘 空间 。 而 
优点 则 是 降低 了 上 游 服务 需 的 负载 ， 尽 量 把 压力 放 在 Nginx 服 务 器 上 。 





如 果 上 游 服务 器 返回 内 
容 ， 则 不 会 先 完 整地 缓存 到 
Nginx 代 理 服务 器 再 向 客户 
端 转发 ， 而 是 边 接收 边 转发 


Mii 


用 户 发 来 的 请 求 将 会 完 
整地 缓存 到 Nginx 代 理 服务 
器 ， 之 后 才 会 癌 后 端 服 务 
器 转发 ， 这 与 Squid 等 反 上 向 


OO 代理 服务 器 不 同 


缓存 请 求 的 HTTP 包 体 
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Nginx 反 向 代理 服务 
器 可 以 根据 多 种 方案 
从 上 游 服务 器 的 集群 
中 选择 一 台 。 它 的 负 
载 均 衡 方案 包括 按 IP| ”一 一 
地 址 做 散 列 等 
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图 2-4 Neginx 作 为 反 向 代理 服务 器 时 转发 请 求 的 流程 


Nginx 的 这 种 工作 方式 为 什么 会 降低 上 游 服务 器 的 负载 呢 ? 通 冲 ， 
客户 端 与 代理 服务 器 之 间 的 网 络 环境 会 比较 复杂 ， 多 半 和 是 “ 走 ” 公 网 ， 网 
速 平均 下 来 可 能 较 慢 ， 因 此 ， 一 个 请 求 可 能 要 持续 很 久 才 能 完成 。 而 代 
理 服务 器 与 上 游 服务 器 之 间 一 般 是 “ 走 ” 内 网 ， 或 者 有 专线 连接 ， 传 输 速 


度 较 快 。Squid 等 反 向 代理 服务 器 在 与 客户 端 建立 连接 且 还 没有 开始 接 
收 HITP 包 体 时 ， 就 已 经 向 上 游 服 务 器 建立 了 连接 。 例 如 ， 某 个 请 求 要 
上 传 一 个 1GB 的 文件 ， 那 么 每 次 Squid 在 收 到 一 个 TCP 分 包 〈 如 2KB) 
时 ， 就 会 即时 地 向 上 游 服 务 器 转发 。 在 接收 客户 端 完 整 HITP 包 体 的 漫 
长 过 程 中 ， 上 游 服务 器 始终 要 维持 这 个 连接 ， 这 直接 对 上 游 服 务 器 的 并 
发 处 理 能 力 提 出 了 挑战 。 


Nginx 则 不 然 ， 它 在 接收 到 完整 的 客户 剖 请 求 ( 如 1GB 的 文件 ) 
后 ， 才 会 与 上 游 服务 器 建立 连接 转发 请 求 ， 由 于 是 内 网 ， 所 以 这 个 转发 
过 程 会 执行 得 很 快 。 这 样 ， 一 个 客户 器 请 求 占 用 上 游 服务 器 的 连接 时 间 
就 会 非常 短 ， 也 就 是 说 ，Nginx 的 这 种 反 回 代理 方案 主要 是 为 了 降低 上 
游 服务 器 的 并 发 压力 。 





Nginx 将 上 游 服务 器 的 啊 应 转发 到 客户 闫 有 许多 种 方法 ， 第 12 章 将 
介绍 其 中 名 见 的 两 种 方式 。 


2.5.1 ”负载 均衡 的 基本 配置 
作为 代理 服务 器 ， 一 般 都 需要 向 上 游 服务 器 的 集群 转发 请 求 。 这 里 


的 负载 均衡 是 指 选 择 一 种 集 略 ， 尺 量 把 请 求 平均 地 分 布 到 每 一 台 上 游 服 
务 嚣 上。 下 面 介 绍 负载 均衡 的 配置 项 。 





(1) upstream 块 


语法 : upstream name{.…} 
配置 块 : http 


upstream 块 定义 了 一 个 上 游 服务 器 的 集群 ， 便 于 反 辐 代理 中 的 
proxy_pass 使 用 。 例 如 : 





upstream backend { 
server backend1.example.com; 
server backend2.example.com; 
server backend3.example.com; 


server { 
location / { 
proxy_pass http://backend; 





(2) server 
语法 : ”server name[parameters]; 
配置 块 : upstream 


server 配 置 项 指定 了 一 台 上 游 服 务 器 的 名 字 ， 这 个 名 字 可 以 是 域 
名 、 耳 地址 端口 、UNIX 句 柄 等 ， 在 其 后 还 可 以 跟 下 列 参数 。 


. weight=numbet: 设置 向 这 台 上 游 服务 器 转发 的 权重 ， 默 认为 1。 


. max_fails=numbet: 该 选项 与 fail_timeout 配 合 使 用 ， 指 在 


Bil_timeout 时 间 段 内 ， 如 果 向 当前 的 上 游 服务 器 转发 失败 次 数 超过 
numbert， 则 认为 在 当前 的 fail_timeout 时 间 段 内 这 台 上 游 服务 器 不 可 用 。 
max_fails 默 认为 1， 如 果 设 置 为 0， 则 表示 不 检查 失败 次 数 。 


fail_timeout=time: fail_timeout 表 示 该 时 间 段 内 转发 失败 多 少 次 后 
就 认为 上 游 服务 器 暂时 不 可 用 ， 用 于 优化 反 向 代理 功能 。 它 与 向 上 游 服 
务 器 建立 连接 的 超时 时 间 、 读 取 上 游 服务 器 的 响应 超时 时 间 等 完全 无 
关 。fail_tmeout 默 认为 10 秒 。 


. down: 表示 所 在 的 上 游 服务 器 永久 下 线 ， 只 在 使 用 ip_hash 配 置 
项 时 才 有 用 。 


:backupb: 在 使 用 ip_hash 配 置 项 时 它 是 无 效 的 。 它 表示 所 在 的 上 游 
服务 器 只 是 备份 服务 器 ， 只 有 在 所 有 的 非 备 份 上 游 服 务 器 都 失效 后 ， 才 
会 向 所 在 的 上 游 服务 器 转发 请 求 。 





例如 : 
upstream backend { 
server backend1 .example.com weight=5; 
server 127.0.0.1:8080 max_fails=3 fail timeout=30s,; 


server unix:/tmp/backend3; 





(3) ip_hash 


语法 : ip_hash:; 


配置 块 : upstream 


在 有 些 场景 下 ， 我 们 可 能 会 希望 来 自 茶 一 个 用 户 的 请 求 始终 落 到 回 
定 的 一 台 上 游 服务 堪 中 。 例 如 ， 假 设 上 游 服务 吉 会 缓存 一 些 信 息 ， 如 果 
同一 个 用 户 的 请 求 任意 地 转发 到 集群 中 的 任 一 人 台 上 游 服务 器 中 ， 那 么 每 
一 台 上 游 服 务 右 都 有 可 能 会 缓存 同一 份 信 息 ， 这 既 会 造成 资源 的 溪 费 ， 
也 会 难以 有 效 地 管理 缓存 信息 。ip_hash 就 是 用 以 解决 上 述 问 题 的 ， 它 首 
先 根据 客户 端的 IP 地 址 计算 出 一 个 key， 将 key 按 照 upstream 集 群 里 的 上 
游 服务 絮 数 量 进行 取 模 ， 然 后 以 取 模 后 的 结果 把 请 求 转发 到 相应 的 上 游 
服务 嚣 中。 这样 束 确 保 了 同一 个 客户 端的 请 求 只 会 转发 到 指定 的 上 游 服 


务 句 中 。 











ip_hash 与 weight〈 权 重 ) 配置 不 可 同时 使 用 。 如 果 upstream 集 群 中 
有 一 人 台 上 游 服 务 器 暂时 不 可 用 ， 不 能 直接 删除 该 配置 ， 而 是 要 down 参 
数 标 识 ， 确 保 转发 策略 的 一 贯 性 。 例 如 : 








upstream backend { 
ip_hash; 
server backend1 .example.com; 
server backend2 .example.com; 
server backend3.example.com down; 
server backend4.example.com; 





(4) 记录 日 志 时 支持 的 变量 


如 果 需 要 将 负载 均衡 时 的 一 些 信息 记录 到 access log 日 志 中 ， 那 么 


在 定义 日 志 格 式 时 可 以 使 用 负载 均衡 功能 提供 的 变量 ， 见 表 2-2。 


表 2-2 访问 上 游 服务 器 时 可 以 使 用 的 变量 


变量 名 意 义 
S$upstream_addr 处 理 请 求 的 上 游 服 务 需 地 址 
S$upstream cache _status 表示 是 否 命 中 缓存 ， 取 值 范围 : MISS、EXPIRED、UPDATING、STALE、HIT 
S$upstream status 上 游 服务 器 返回 的 响应 中 的 HTTP 响应 码 
S$upstream_response_time 上 游 服 务 器 的 响应 时 间 ， 精 度 到 毫秒 
$upstream http_ SHEADER HTTP 的 头 部 ， 如 upstream_http_host 


例如 ， 可 以 在 定义 access_log 访 问 日 志 格式 时 使 用 表 2-2 中 的 变量 。 





log_format timing '$remote addr - $remote user [$time _ local] $request ' 
"upstream_response_time $upstream response_ time ' 
"msec $msec request time $request time'; 

log_format up_head '$remote addr - $remote user [$time local] $request ' 
"Upstream_http_content_type $upstream http_content type'; 





2.5.2 ”反问 代理 的 基本 配置 


下 面 介 绍 反 向 代理 的 基本 配置 项 。 
(1) proxy_pass 

语法 : proxy_pass URL; 

配置 块 : location、 证 


此 配置 项 将 当前 请 求 反 向 代理 到 URL 参 数 指定 的 服务 器 上 ，URL 可 
以 是 主机 名 或 卫 地 址 加 问 口 的 形式 ， 例 如 : 








proxy_pass http://localhost:8000/uri/ 





也 可 以 是 UNIX 句 柄 ; 





proxy_pass http://unix:/path/to/backend.socket:/uri/ 





还 可 以 如 上 节 负 载 均衡 中 所 示 ， 直 接 使 用 upstream 块 ， 例 如 : 





upstream backend { 


server { 
location / { 
proxy_pass http://backend 





用 户 可 以 把 HTTP 转 换 成 更 安全 的 HTTPS， 例 如 : 





proxy_pass https://192.168.0.1 








默认 情况 下 反 辐 代理 是 不 会 转发 请 求 中 的 Host 头 部 的 。 如 果 需 要 转 
发 ， 那 么 必须 加 上 配置 : 





proxy_set_header Host $host; 





(2) proxy_method 
语法 : proxy_method method; 
配置 块 : http、server、location 


此 配置 项 表示 转发 时 的 协议 方法 名 。 例 如 设置 为 : 





proxy_method POST ; 





那么 客户 疹 发 来 的 GET 请 求 在 转发 时 方法 名 也 会 改 为 POST。 
(3) proxy_hide header 
语法 : proxy_hide_header the_header; 
配置 块 : http、server、location 


Nginx 会 将 上 游 服务 器 的 啊 应 转发 给 客户 端 ， 但 默认 不 会 转发 以 下 
HTTP 头 部 字段 : Date、Server、X-Pad 和 X-Accel-*。 使 用 
proxy_hide_ header 后 可 以 任意 地 指定 哪些 HITP 头 部 字段 不 能 被 转发 。 
例如 : 








proxy_hide_header Cache-Control; 
proxy_hide_header MicrosoftofficewebServer ; 





(4) proxy_pass_header 
语法 : proxy_pass_header the_header; 
配置 块 : http、server、location 


与 proxy_hide_header 功 能 相反 ，proxy_pass_header 会 将 原来 禁止 转 
发 的 header 设 置 为 允许 转发 。 例 如 : 





proxy_pass_header X-Accel-Redirect,; 





(5) proxy_pass_request_ body 

语法 : proxy_pass_request_body onloff; 

默认 : proxy_pass_request_body on; 

配置 块 : http、server、location 

作用 为 确定 是 否 同 上 游 服 务 器 发 送 HTTP 包 体 部 分 。 
(6) proxy_pass_request_headers 

语法 : proxy_pass_request_headers onloff; 


默认 : proxy_pass_request_headers on; 


配置 块 : http、server、location 
作用 为 确定 是 人 否 转发 HTTP 头 部 。 
(7) proxy_redirect 
语法 : proxy_redirect[defaultlofflredirect replacement]; 
默认 : proxy_redirect default; 


配置 块 : http、server、location 





当 上 游 服务 器 返回 的 啊 应 是 重 定 同 或 刷新 请 求 〈“ 如 HITP 啊 应 码 是 
301 或 者 302) 时 ，Pproxy_redirect 可 以 重 设 HITTP 头 部 的 location 或 refresh 
字段 。 例 如 ， 如 果 上 游 服务 器 发 出 的 啊 应 是 302 重 定 问 请 求 ，location 字 
段 的 URI 是 http://localhost:8000/two/some/uri/ ， 那 么 在 下 面 的 配置 情况 





下 ， 实 际 转发 给 客户 端的 location 是 http://frontend/one/some/uri/ 。 





proxy_redirect http://localhost:8000/two/ 


htto:Z/trontend/oners 





这 里 还 可 以 使 用 ngx-http-core-module 提 供 的 变量 来 设置 新 的 location 
字段 o 例 如 。 





proxy_redirect http://localhost:8000/ 


http://$host:$server_port7; 





也 可 以 省 略 replacement 参 数 中 的 主机 名 部 分 ， 这 时 会 用 虚拟 主机 名 
称 来 填充 。 例 如 : 





proxy_redirect http://localhost:8000/two//one/ 





使 用 off 参 数 时 ， 将 使 location 或 者 refresh 字 有 段 维 持 不 变 。 例 如 : 





proxy_redirect off; 





使 用 默认 的 default 参 数 时 ， 会 按照 proxy_pass 配 置 项 和 所 属 的 
location 配 置 项 重组 发 往 客 户 端的 location 头 部 。 例 如 ， 下 面 两 种 配置 效 
果 是 一 样 的 : 





Jocation /one/ { 
proxy_pass http://upstream:port/two/ 


proxy_redirect default; 


location /one/ { 
proxy_pass http://upstream:port/two/ 


proxy_redirect http://upstream:port/two//one/ 


(8) proxy_next_upstream 


语法 : 


proxy_next_upstreaml[errorltimeoutlinvalid_header|lhttp_500|http_502|http_50, 
默认 : proxy_next_upstream error timeout; 
配置 块 : http、server、l]ocation 


此 配置 项 表示 当 向 一 台 上 游 服 务 器 转发 请 求 出 现 错误 时 ， 继 续 换 一 
台 上 游 服务 器 处 理 这 个 请 求 。 前 面 已 经 说 过 ， 上 游 服 务 器 一 旦 开始 发 送 
应 答 ，Nginx 反 向 代理 服务 器 会 立刻 把 应 答 包 转发 给 客户 端 。 因 此 ， 
旦 Nginx 开 始 向 客户 端 发 送 响 应 包 ， 之 后 的 过 程 中 若 出 现 错误 也 是 不 多 
许 换 下 一 台 上 游 服务 器 继续 处 理 的 。 这 很 好 理解 ， 这 样 才 可 以 更 好 地 保 
证 客户 端 只 收 到 来 自 一 个 上 游 服务 器 的 应 答 。proxy_next_upstream 的 参 
数 用 来 说 明 在 哪些 情况 下 会 继续 选择 下 一 台 上 游 服 务 器 转发 请 求 。 








.ettof: 当 向 上 游 服务 器 发 起 连接 、 发 送 请 求 、 读 取 响 应 时 出 错 
. timeout: 发 送 请 求 或 读 取 响应 时 发 生 超时 。 
invalid_header: 上 游 服 务 器 发 送 的 响应 是 不 合法 的 。 


` http_500: 上 游 服务 器 返回 的 HTTP 响 应 码 是 500。 


.http_502: 上 游 服 务 器 返回 的 HTTP 响 应 码 是 502。 
` http_503: 上 游 服务 器 返回 的 HTTP 响应 码 是 503。 
` http_504: 上 游 服务 器 返回 的 HTTP 响 应 码 是 504。 
-http_404: 上 游 服 务 器 返回 的 HTTP 响 应 码 是 404。 


off: 关闭 ptfoxy_next_upstteam 功 能 一 出 错 就 选择 另 一 台 上 游 服务 


器 再 次 转发 。 


Nginx 的 反 向 代理 模块 还 提供 了 很 多 种 配置 ， 如 设置 连接 的 超时 时 
间 、 临 时 文件 如 何 存储 ， 以 及 最 重要 的 如 何 缓存 上 游 服 务 器 响应 等 功 
能 。 这 些 配置 可 以 通过 阅读 ngx_http_proxy_module 模 块 的 说 明了 解 ， 只 
有 深入 地 理解 ， 才 能 实现 一 个 高 性 能 的 反 向 代理 服务 器 。 本 节 只 是 介绍 
反 向 代理 服务 器 的 基本 功能 ， 在 第 12 章 中 我 们 将 会 深入 地 探索 upstream 
机 制 ， 到 那 时 ， 读 者 也 许 会 发 现 ngx_http_proxy_module 模 块 只 是 使 用 
upstream 机 制 实现 了 反 向 代理 功能 而 已 。 


2.6 小结 


Nginx 由 少量 的 核心 框架 代码 和 许多 模块 组 成 ， 每 个 模块 都 有 它 独 
特 的 功能 。 因 此 ， 读 者 可 以 通过 查看 每 个 模块 实现 了 什么 功能 ， 来 了 解 
Nginx 可 以 帮 我 们 做 些 什么 。 


Nginx 的 Wiki 网 站 《http://wiki.nginx.org/Modules ) 上 列 出 了 官方 提 
供 的 所 有 模块 及 配置 项 ， 和 仔细 观察 就 会 发 现 ， 这 些 配置 项 的 语法 与 本 章 
的 内 容 都 是 很 相近 的 ， 读 者 只 需要 弄 清楚 模块 说 明 中 每 个 配置 项 的 意义 
即 可 。 另 外 ， 网 页 http://wiki.nginx.org/3rdPartyModules 中 列 出 了 Wiki 上 
已 知 的 几 十 个 第 三 方 模块 ， 同 时 读者 还 可 以 从 搜索 引擎 上 搜索 到 更 多 的 
第 三 方 模块 。 了 解 每 个 模块 的 配置 项 用 法 ， 并 在 Nginx 中 使 用 这 些 模 
块 ， 可 以 让 Nginx 做 到 更 多 。 








随 着 对 本 书 的 学 习 ， 读 者 会 对 Nginx 模 块 的 设计 思路 有 深入 的 了 
解 ， 也 会 渐渐 熟 悉 如 何 编写 一 个 模块 。 如 果 茶 个 模块 的 实现 与 你 的 想法 
有 出 入 ， 可 以 更 改 这 个 模块 的 源码 ， 实 现 你 期 望 的 业务 功能 。 如 果 所 有 
的 模块 部 没有 你 想 要 的 功能 ， 不 妨 自 己 重 写 一 个 定制 的 模块 ， 也 可 以 申 
请 发 布 到 Nginx 网 站 上 供 大 家 分 享 。 





第 二 部 分 “如 何 编号 HTTP 模块 
开发 一 个 简单 的 HTTP 模 块 

配置 、ettot 日 志和 请 求 上 下 文 
访问 第 三 方 服务 

开发 一 个 简单 的 HTTP 过 滤 模 块 


Nginx 提 供 的 高 级 数据 结构 





第 3 半 ”开发 一 个 简单 的 HTTP 模 块 


当 通 过 开发 HTTP 模 块 来 实现 产品 功能 时 ， 是 可 以 完全 享用 Nginx 的 
优秀 设计 所 带 来 的 、 与 官方 模块 相同 的 高 并 发 特性 的 。 不 过 ， 如 何 开发 
一 个 充满 异步 调用 、 无 阻塞 的 HTTP 模 块 呢 ? 首先 ， 需 要 把 程序 坐 入 到 
Nginx 中 ， 也 就 是 说 ， 最 终 编 译 出 的 二 进 制 程序 Nginx 要 包含 我 们 的 代码 

( 见 3.3 节 ) ; 其 次 ， 这 个 全 新 的 HTTP 模 块 要 能 介入 到 HTTP 请 求 的 处 
理 流程 中 (具体 参见 3.1 节 、3.4 节 、3.5 节 ) 。 满 足 上 述 两 个 前 提 后 ， 我 
们 的 模块 才能 开始 处 理 HTTP 请 求 ， 但 在 开始 处 理 请 求 前 还 需要 先 了 解 
一 些 Nginx 框 架 定 义 的 数据 结构 〈 见 3.2 节 ) ， 这 是 后 面 必须 要 用 到 的 ; 
正式 处 理 请 求 时 ， 还 要 可 以 获得 Nginx 框 架 接收 、 解 析 后 的 用 户 请 求 信 
恩 〈 见 3.6 节 ) ; 业务 执行 完毕 后 ， 则 要 考虑 发 送 响应 给 用 户 《 见 3.7 

) ， 包 括 将 磁盘 中 的 文件 以 HTTP 包 体 的 形式 发 送 给 用 户 ( 见 3.8 
站 





节 
节 





本 章 最 后 会 讨论 如 何 用 C++ 语言 来 编写 HTTP 模块 ， 这 虽然 不 是 
Nginx 官 方 倡 导 的 方式 ， 但 C++ 疝 前 兼容 C 语 言 ， 使 用 C++ 语言 开发 的 模 
块 还 是 可 以 很 容易 地 磐 入 到 Nginx 中 。 本 章 不 会 深入 探讨 HTTP 模块 与 
Nginx 的 各 个 核心 模块 是 如 何 配合 工 作 的 ， 而 且 这 部 分 提 到 的 每 个 接口 
将 只 涉及 用 法 而 不 涉及 实现 原理 ， 在 第 3 部 分 我 们 才 会 进一步 阐述 本 章 
提 到 的 许多 接口 是 如 何 实现 异步 访问 的 。 














3.1 如 何 调用 HTTP 模 块 


在 开发 HTTP 模 块 前 ， 首 先 需 要 了 解 典 型 的 HTTP 模 块 是 如 何 介入 
Nginx 处 理 用 户 请 求 流程 的 。 图 3-1 是 一 个 简化 的 时 序 图 ， 这 里 省 略 了 许 
多 异步 调用 ， 忽 略 了 多 个 不 同 的 HITP 处 理 阶 段 ， 仅 标识 了 在 一 个 典型 
请 求 的 处 理 过 程 中 主要 模块 被 调用 的 流程 ， 以 此 帮助 读者 理解 HTTP 模 
块 如 何 处 理 用 户 请 求 。 完 整 的 流程 将 在 第 11 章 中 详细 介绍 。 
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图 3-1 Nginx HTTP 模 块 调用 的 简化 流程 


从 图 3-1 中 看 到 ，worker 进 程 会 在 一 个 for 循 环 语 句 里 反复 调用 事件 
模块 检测 网 络 事件 。 当 事件 模块 检测 到 某 个 客户 端 发 起 的 TCP 请 求 时 
(接收 到 SYN 包 ) ， 将 会 为 它 建立 TCP 连 接 ， 成 功 建立 连接 后 根据 
nginx.conf 文 件 中 的 配置 会 交 由 HTTP 框 架 处 理 。HTTP 框 架 会 试图 接收 
完整 的 HITP 头 部 ， 并 在 接收 到 完整 的 HTTP 头 部 后 将 请 求 分 发 到 具体 的 





HTTP 模 块 中 处 理 。 这 种 分 发 策略 是 多 样 化 的 ， 其 中 最 常见 的 是 根据 请 
求 的 URI 和 nginx.conf 里 location 配 置 项 的 匹配 度 来 决定 如 何 分 发 (本 章 
的 例子 正 是 应 用 这 种 分 发 策略 ， 在 第 10 章 中 会 介绍 其 他 分 发 策略 ) 。 
HTTP 模 块 在 处 理 请 求 的 结束 时 ， 大 多 会 向 客户 端 发 送 响应 ， 此 时 会 自 
动 地 依次 调用 所 有 的 HTTP 过 滤 模 块 ， 每 个 过 滤 模 块 可 以 根据 配置 文件 
决定 自己 的 行为 。 例 如 ，gzip 过 滤 模 块根 据 配置 文件 中 的 gzip onloff 来 决 
定 是 侣 压缩 啊 应 。HTTP 处 理 模 块 在 返回 时 会 将 控制 权 交 还 给 HTTP 框 
架 ， 如 果 在 返回 前 设置 了 subrequest， 那 么 HTTP 框 架 还 会 继续 异步 地 调 
用 适合 的 HITP 模 块 处 理子 请 求 。 











开发 HTTP 模 块 时 ， 首 先 要 注意 的 就 是 HTTP 框 架 到 具体 的 HTTP 模 
块 间 数据 流 的 传递 ， 以 及 开发 的 HTTP 模 块 如 何 与 诸多 的 过 滤 模 块 协同 
工作 (第 10 章 、 第 11 章 会 详细 介绍 HTTP 框 架 ) 。 下 面 正 式 进 入 HTTP 模 
块 的 开发 环节 。 





3.2 ”准备 工作 


Nginx 模 块 需要 使 用 C (或 者 C++) 语言 编写 代码 来 实现 ， 每 个 模块 
都 要 有 自己 的 名 字 。 按 照 Nginx 约 定 俗 成 的 命名 规则 ， 我 们 把 第 一 个 
HTTP 模 块 命名 为 ngx_http_mytest module。 由 于 第 一 个 模块 非常 简单 ， 
一 个 C 源 文件 就 可 以 完成 ， 所 以 这 里 按照 官方 惯例 ， 将 唯一 的 源 代码 文 


件 命名 为 ngx_http_mytest_module.c。 











实际 上 ， 我 们 还 需要 定义 一 个 名 称 ， 以 便 在 编译 前 的 configure 命 令 
执行 时 显示 是 否 执行 成 功 〈 即 configure 脚 本 执行 时 的 ngx_addon_name 变 
量 ) 。 为 方便 理解 ， 仍 然 使 用 同一 个 模块 名 来 表示 ， 如 


ngx_http_mytest moduje。 








为 了 让 HTTP 模 块 正 党 工作， 首先 需要 把 它 编译 进 Nginx 〈3.3 节 会 
探讨 编译 新 增 模块 的 两 种 方式 ) 。 其 次 需要 设 定 模块 如 何在 运行 中 生 
效 ， 比 如 在 图 3-1 描 述 的 典型 方式 中 ， 配 置 文件 中 的 location 块 决定 了 匹 
配 某 种 URI 的 请 求 将 会 由 相应 的 HTTP 模 块 处 理 ， 因 此 ， 运 行 时 HTTP 框 
架 会 在 接收 完毕 HTTP 请 求 的 头 部 后 ， 将 请 求 的 URI 与 配置 文件 中 的 所 
有 location 进 行 匹 配 《〈 事 实 上 会 优先 匹配 虚拟 主机 ， 第 11 章 会 详细 说 明 
该 流程 》， 匹 配 后 再 根据 location{} 内 的 配置 项 选择 HTTP 模 块 来 调用 。 
这 是 一 种 最 典型 的 HTTP 模 块 调用 方式 。3.4 节 将 解释 HTTP 模 块 定义 组 








入 方式 时 用 到 的 数据 结构 ，3.5 节 将 定义 我 们 的 第 一 个 HTTP 模 块 ，3.6 市 
中 介绍 如 何 使 用 上 述 模块 调用 方式 来 处 理 请 求 。 


既然 有 典型 的 调用 方式 ， 自 然 也 有 非典 型 的 调用 方式 ， 比 如 
ngx_http_access_module 模 块 ， 它 是 根据 IP 地 址 决定 菜 个 客户 病 是 否 可 以 
访问 服务 的 ， 因 此 ， 这 个 模块 需要 在 NGX_HTTP_ACCESS_PHASE 阶 段 

《在 第 10 章 中 会 详 述 HTTP 框 架 定 义 的 11 个 阶段 ) 生效 ， 它 会 比 本 章 介 
绍 的 mytest 模 块 更 早 地 介入 请 求 的 处 理 中 ， 同 时 它 的 流程 与 图 3-1 中 的 不 
同 ， 它 可 以 对 所 有 请 求 产生 作用 。 也 就 是 说 ， 任 何 HITP 请 求 都 会 调用 
ngx_http_access_module 模 块 处 理 ， 只 是 该 模块 会 根据 它 感 兴趣 的 配置 项 
及 所 在 的 配置 块 来 决定 行为 方式 ， 这 与 mytest 模 块 不 同 ， 在 mytest 模 块 
中 ， 只 有 在 配置 了 location/uri{mytest;} 后 ，HTTP 框 架 才 会 在 某 个 请 求 匹 
配 了 /uri 后 调用 它 处 理 请 求 。 如 果 菏 个 匹配 了 URI 请 求 的 location 中 没有 
配置 mytest 配 置 项 ，mytest 模 块 依然 是 不 会 被 调用 的 。 








为 了 做 到 路 平台 ，Nginx 定 义 、 封 装 了 一 些 基本 的 数据 结构 。 由 于 
Nginx 对 内 存 分 配 比较 “ 音 亩 ”〈 只 有 保证 低 内 存 消 耗 ， 才 可 能 实现 十 万 
甚至 百 万 级 别 的 同时 并 发 连接 数 ) ， 所 以 这 些 Nginx 数 据 结构 天 生 都 是 
尽 可 能 少 占 用 内 存 。 下 面 介绍 本 章 中 将 要 用 到 的 Nginx 定 义 的 几 个 基本 
数据 结构 和 方法 ， 在 第 7 章 还 会 介绍 一 些 复 杂 的 容器 ， 读 者 可 以 从 中 体 
会 到 如 何 才 能 有 效 地 利用 内 存 。 





3.2.1 整 型 的 封装 


Nginx 使 用 ngx_int_t 封 装 有 符号 整 型 ， 使 用 ngx_uint_t 封 装 无 符号 整 
型 。Nginx 各 模块 的 变量 定义 都 是 如 此 使 用 的 ， 建 议 读者 沿用 Nginx 的 习 
惯 ， 以 此 蔡 代 int 和 unsinged int。 


在 Linux 平 台 下 ，Nginx 对 ngx_int_t 和 ngx_uint_t 的 定义 如 下 : 





typedef intptr_t ngx_int_t; 
typedef uintptr_t ngx_uint_t; 





3.2.2 ngx_str_t 数 据 结构 


在 Nginx 的 领域 中 ，ngx_str_t 结 构 就 是 字符 串 。ngx_str_t 的 定义 如 





下 : 
typedef struct { 
size_t len; 
u_char *data; 
} ngx_str_t; 





ngx_str_t 只 有 两 个 成 员 ， 其 中 data 指 针 指 向 字符 串 起 始 地 址 ，len 表 
示 字 符 串 的 有 效 长 度 。 注 意 ，ngx_str_t 的 data 成 员 指 向 的 并 不 是 普通 的 
字符 串 ， 因 为 这 段 字符 串 未 必 会 以 \0' 作 为 结尾 ， 所 以 使 用 时 必须 根据 长 
度 len 来 使 用 data 成 员 。 例 如 ， 在 3.7.2 节 中 ， 我 们 会 看 到 r->method_name 
就 是 一 个 ngx_str_t 类 型 的 变量 ， 比 较 method_name 时 必须 如 下 这 样 使 





用 : 





if (0 == ngx_Sstrncmp( 
r->method_name .data， 
mh PUT mh 
r->method_name.1len) 





这 里 ，ngx_strmncmp 其 实 就 是 strmncmp 函 数 ， 为 了 路 平台 Nginx 习 惯性 
地 对 其 进行 了 名 称 上 的 封装 ， 下 面 看 一 下 扬 的 定义 : 





#define ngx_strncmp(S1，S2，n) strncmp((const char *) S1，(const char *) s2, n) 





任何 试图 将 ngx_str_t 的 data 成 员 当 做 字符 串 来 使 用 的 情况 ， 都 可 能 
导致 内 存 越界 ! Nginx 使 用 ngx_str_t 可 以 有 效 地 降低 内 存 使 用 量 。 例 
如 ， 用 户 请 求 “GET/testa=1 http/1.1mn” 存 储 到 内 存 地 址 0x1d0b0110 上 ， 
这 时 只 雷 要 把 r->method_name 设 置 为 {len=3,data=0x1d0b0110} 就 可 以 表 
示 方 法 名 “GET”， 而 不 需要 单独 为 method_name 再 分 配 内 存 宛 余 的 存储 


字符 串 。 





3.2.3 ngx_list_t 数 据 结构 


ngx_list_t 是 Nginx 封 装 的 链表 容器 ， 它 在 Nginx 中 使 用 得 很 频繁 ， 例 
如 HTTP 的 涉 部 就 是 用 ngx_list_t 来 存储 的 。 当 然 ，C 语 言 封装 的 链表 没有 
C++ 或 Java 等 面 同 对 象 语言 那么 容易 理解 。 先 看 一 下 ngx_list_t 相 关 成 员 


的 起 义 : 





typedef struct ngx_ list part_s ngx_list part 七 ; 
struct ngx_list part s { 

void *elts,; 

ngx_uint_t nelts,; 

ngx_list part t *next; 





/ 
typedef struct { 
ngx_list_ part t *]J]ast; 
ngx_list_part_t part 


size_t size; 
ngx_uint_t nalloc; 
ngx_pool_t *pool; 


} ngx_list_t; 





ngx_list_t 描 述 整 个 链表 ， 而 ngx_list_part_t 只 描述 链表 的 一 个 元 素 。 

这 里 要 注意 的 是 ，ngx_list_t 不 是 一 个 单纯 的 链表 ， 为 了 便于 理解 ， 我 们 
姑且 称 它 为 存储 数组 的 链表 ， 什 么 意思 呢 ? 抽象 地 说 ， 就 是 每 个 链表 元 
素 ngx_list_part_t 义 是 一 个 数组 ， 拥 有 连续 的 内 存 ， 它 既 依 赖 于 ngx_list_t 
里 的 size 和 nalloc 来 表示 数组 的 容量 ， 同 时 又 依靠 每 个 ngx_list_part_t 成 员 
中 的 nelts 来 表示 数组 当前 已 使 用 了 多 少 容 量 。 因 此 ，ngx_list_t 是 一 个 链 
表 容 占 ， 而 链表 中 的 元 素 又 是 一 个 数组 。 事实 上 ，ngx_list_part_t 数 组 中 
的 元 素 才 是 用 户 想 要 存储 的 东西 ，ngx_list_t 链 表 能 够 容纳 的 元 素数 量 由 
ngx_list_part_t 数 组 元 系 的 个 数 与 每 个 数组 所 能 容纳 的 元 素 相 乘 得 到 。 


这 样 设计 有 什么 好 处 呢 ? 
" 链表 中 存储 的 元 素 是 灵活 的 ， 它 可 以 是 任何 一 种 数据 结构 。 


` 链表 元 素 需 要 占用 的 内 存 由 ngx_list_t 管 理 ， 它 已 经 通过 数组 分 配 


好 了 。 


-小 块 的 内 存 使 用 链表 访问 效率 是 低下 的 ， 使 用 数组 通过 偏 移 量 来 
直接 访问 内 存 则 要 高 效 得 多 。 





下 面 详 述 每 个 成 员 的 意义 。 
(1) ngx_list t 
- patt: 链表 的 首 个 数组 元 素 。 
.last: 指向 链表 的 最 后 一 个 数组 元 素 。 


. size: 前 面 讲 过 ， 链 表 中 的 每 个 hgx_list_part_t 元 素 都 是 一 个 数 
组 。 因 为 数组 存储 的 是 某 种 类 型 的 数据 结构 ， 且 ngx_list_t 是 非常 灵活 的 
数据 结构 ， 所 以 它 不 会 限制 存储 什么 样 的 数据 ， 只 是 通过 size 限 制 每 一 
个 数组 元 素 的 占用 的 空间 大 小 ， 也 就 是 用 户 要 存储 的 一 个 数据 所 占用 的 


字 节 数 必 须 小 于 或 等 于 size。 


. nalloc: 链表 的 数组 元 素 一 旦 分 配 后 是 不 可 更 改 的 。nalloc 表 示 每 


个 ngx_jist_patt_t 数 组 的 容量 ， 即 最 多 可 存储 多 少 个 数据 。 


pool: 链表 中 管理 内 存 分 配 的 内 存 池 对 象 。 用 户 要 存放 的 数据 占 
用 的 内 存 都 是 由 pool 分 配 的 ， 下 文中 会 详细 介绍 。 


(2) ngx_list_part t 


elts: 指向 数组 的 起 始 地 址 。 


.nelts: 表示 数组 中 已 经 使 用 了 多 少 个 元 素 。 当 然 ，nelts 必 须 小 于 
ngx_list_t 结 构 体 中 的 nalloc。 


.next: 下 一 个 链表 元 素 ngx_list_part_t 的 地 址 。 


事实 上 ，ngx_list_t 中 的 所 有 数据 都 是 由 ngx_pool_t 类 型 的 pool 内 存 
池 分 配 的 ， 它 们 通常 都 是 连续 的 内 存 (在 由 一 个 pool 内 存 池 分 配 的 情况 
下 ) 。 下 面 以 图 3-2 为 例 来 看 一 下 ngx_list_t 的 内 存 分 布 情况 。 


ngx_list_t 














Ngx_list_part_t (3) 


Negx_list_part_t ( Ngx_list_part_t (2) 








本 段 内 存 存储 本 上 段 内 存 存储 本 段 内 存 存储 本 段 内 存 存 储 
nex_list_1 nex _list nex_list nex_list 
结构 part_t (1) part_t (2) part_t (3) 
结构 结构 结构 


图 3-2 ”ngx_list_t 的 内 存 分 布 


图 3-2 中 是 由 3 个 ngx_list_part_t 数 组 元 素 组 成 的 ngx_list_t 链 表 可 能 拥 
有 的 一 种 内 存 分 布 结 构 ， 读 者 可 以 从 这 种 较为 常见 的 内 存 分 布 中 看 到 
ngx_list_t 链 表 的 用 法 。 这 里 ，pool 内 存 池 为 其 分 配 了 连续 的 内 存 ， 最 前 
端 内 存 存储 的 是 ngx_list_t 结 构 中 的 成 员 ， 紧 接着 是 第 一 个 ngx_list_part_t 
结构 占用 的 内 存 ， 然 后 是 ngx_list_part_t 结 构 指 向 的 数组 ， 它 们 一 共 占 用 
size*nalloc 字 节 ， 表 示 数 组 中 拥有 nalloc 个 大 小 为 size 的 元 素 。 其 后 面 是 
第 2 个 ngx_list_part_t 结 构 以 及 它 所 指 癌 的 数组 ， 依 此 类 推 。 


对 于 链表 ，Nginx 提 供 的 接口 包括 : ngx_list_create 接 口 用 于 创建 新 
的 链表 ，ngx_list_init 接 口 用 于 初始 化 一 个 已 有 的 链表 ，ngx_list_push 接 
口 用 于 添加 新 的 元 素 ， 如 下 所 示 : 





ngx_list_t *ngx_list create(ngx_pool t *pool, ngx_uint_t n, size _t size),; 
static ngx_inline ngx_int_t 

ngx_list_init(ngx_list_t *list, ngx_pool t *pool, ngx_uint_t n, size_t size); 
void *ngx_list push(ngx_list t *1list); 








调用 ngx_list_create 创 建 元 素 时 ，pool 参 数 是 内 存 池 对 象 ( 参 见 3.7.2 
节 ) ，size 是 每 个 元 素 的 大 小 ，n 是 每 个 链表 数组 可 容纳 元 素 的 个 数 〈 相 
当 于 ngx_list_t 结 构 中 的 nalloc 成 员 ) 。ngx_list_create 返 回 新 创建 的 链表 
地 址 ， 如 果 创 建 失败 ， 则 返回 NULL 空 指针 。ngx_list_create 被 调用 后 至 
少 会 创建 一 个 数组 (不 会 创建 空 链表 ) ， 其 中 包含 n 个 大 小 为 size 字 节 的 
连续 内 存 块 ， 也 就 是 ngx_list_t 结 构 中 的 part 成 员 。 





下 面 看 一 个 简单 的 例子 ， 我 们 首先 建立 一 个 链表 ， 它 存储 的 元 素 古 


ngx_str_ t， 其 中 每 个 链表 数组 中 存储 4 个 元 系 ， 代 码 如 下 所 示 : 





ngx_list_t* testlist = ngx_list create(r->pool, 4,sizeof(ngx_str_t)); 
if (testlist == NULL) { 

return NGX_ERROR; 
} 





ngx_list_init 的 使 用 方法 与 ngx_list_create 非 常 类 似 ， 需 要 注音 的 是 ， 
这 时 链表 数据 结构 已 经 创建 好 了 ， 若 ngx_list_init 返 回 NGX_OK， 则 表示 
初始 化 成 功 ， 若 返回 NGX_ERROR， 则 表示 失败 。 


调用 ngx_list_push 表 示 钦 加 新 的 元 素 ， 传 入 的 参数 是 ngx_list_t 链 
表 。 正 常情 况 下 ， 返 回 的 是 新 分 配 的 元 素 首 地 址 。 如 果 返 回 NULL 空 指 
针 ， 则 表示 添加 失败 。 在 使 用 它 时 通常 先 调 用 ngx_list_push 得 到 返回 的 
元 素 地 址 ， 再 对 返回 的 地 址 进行 赋值 。 例 如 





ngx_str_t* Str = ngx_list_push(test]list),; 
if (str == NULL) { 
return NGX_ERROR,; 


} 
str->len= sizeof("Hello world"); 
str->data = "Hello world"; 








过 历 链 表 时 Nginx 没 有 提供 相应 的 接口 ， 实 际 上 也 不 需要 。 我 们 可 
以 用 以 下 方法 过 有 历 链表 中 的 元 素 : 





// part 用 于 指向 链表 中 的 每 一 个 


ngx_list_part_t 数 组 


ngx_list_part_t* part = &testlist.part,; 


// 根据 链表 中 的 数据 类 型 ， 把 数组 里 的 


elts 转 化 为 该 类 型 使 用 


ngx_str_t* str = part->elts,; 
// 表示 元 素 在 链表 的 每 个 


ngx_list_part_t 数 组 里 的 序号 


for (i = 0; /* void */; i++) { 
if (i >= part->nelts) { 
if (part->next == NULL) { 
// 如 果 某 个 


ngx_list_part_t 数 组 的 
next 指 针 为 空 ， 
// 则 说 明 已 经 遍历 完 链表 
break; 
} 
// 访问 下 一 个 


ngx_list part_t 
part = part->next,; 
str = part->elts 
// 将 


@， 准 备 重新 访问 下 一 个 数组 





= 0; 


} 
// 这 里 可 以 很 方便 地 取 到 当前 遍历 到 的 链表 元 素 


printf("list element: %*s\n",str[i].len, str[i].data); 





3.2.4 ngx_table_elt_t 数 据 结 构 


ngx_table_elt_t 数 据 结 构 如 下 所 示 : 





typedef struct { 


ngx_uint_t hash,; 
ngx_str_t key; 
ngx_str_t value; 


u_char *lowcase_key; 
} ngx_table elt_t; 





可 以 看 到 ，ngx_table_elt_t 就 是 一 个 key/value 对 ，ngx_str_t 类 型 的 
key、value 成 员 分 别 存 储 的 是 名 字 、 值 字符 串 。hash 成 员 表 明 
ngx_table_elt_t 也 可 以 是 某 个 散 列 表 数 据 结 构 (ngx_hash_t 类 型 ) 中 的 成 
员 。ngx_uint_t 类 型 的 hash 成 员 可 以 在 ngx_hash_t 中 更 快 地 找到 相同 key 
的 ngx_table_elt_t 数 据 。lowcase_key 指 问 的 是 全 小 写 的 key 字 符 串 。 


显而易见 ，ngx_table_elt_t 是 为 HITP 头 部 “ 量 身 订 制 ”的 ， 其 中 key 存 
储 头 部 名 称 〈 如 Content-Length) ，value 存 储 对 应 的 值 (如 “1024”) ， 
lowcase_key 是 为 了 忽略 HTTP 头 部 名 称 的 大 小 写 〈 例 如 ， 有 些 客户 端 发 
来 的 HTTP 请 求 头 部 是 content-length，Nginx 希 望 它 与 大 小 写 敏 感 的 
Content-Length 做 相同 处 理 ， 有 了 全 小 写 的 lowcase_key 成 员 后 就 可 以 快 
速达 成 目的 了 ) ，hash 用 于 快速 检索 头 部 《〈 它 的 用 法 在 3.6.3 节 中 进行 详 














总 


3.2.5 ngx_buf {t 数 据 结构 





缓冲 区 ngx_buf t 是 Nginx 处 理 大 数据 的 关键 数据 结构 ， 它 既 应 用 于 
内 存 数据 也 应 用 于 磁盘 数据 。 下 面 主要 介绍 ngx_buf t 结 构 体 本 吴 ， 而 描 
述 磁盘 文件 的 ngx_file t 结 构 体 则 在 3.8.1 节 中 说 明 。 下 面 来 看 一 下 相关 代 
人 码 : 





typedef struct ngx_ buf_s ngx_buf_t; 
typedef void * ngx_buf_tag_t; 
struct ngx_buf_s { 

/*pos 通 常 是 用 来 告诉 使 用 者 本 次 应 该 从 





pos 这 个 位 置 开 始 处 理 内 存 中 的 数据 ， 这 样 设置 是 因为 同一 个 
ngx_buf_t 可 能 被 多 次 反复 处 理 。 当 然 ， 
pos 的 含义 是 由 使 用 它 的 模块 定义 的 


4 
u_char *pos; 
/*last 通 常 表示 有 效 的 内 容 到 此 为 止 ， 注意 ， 


pos 与 
last 之 间 的 内 存 是 希望 
nginx 处 理 的 内 容 


* 
u_char *last; 
A/* 处 理 文件 时 ， 


file_pos 与 

file_last 的 含义 与 处 理 内 存 时 的 
pos 与 

last 相 同 ， 


file_pos 表 示 将 要 处 理 的 文件 位 置 ， 


file_last 表 示 截 止 的 文件 位 置 


“yy 
off_t file_pos; 
off_t file_last,; 
// 如 果 


ngx_buf _t 缓 冲 区 用 于 内 存 ， 那 么 


Start 指 向 这 段 内 存 的 起 始 地 址 


u_char *start; 
/7 与 


Start 成 员 对 应 ， 指 向 缓冲 区 内 存 的 末尾 


u_char *end; 
/* 表 示 当 前 缓冲 区 的 类 型 ， 例 如 由 哪个 模块 使 用 就 指向 这 个 模块 


ngx_modu]le 七 变量 的 地 址 


2 
ngx_buf_tag_t tag ; 
// 引用 的 文件 
ngx_file 七 *file; 


/* 当 前 缓冲 区 的 影子 缓冲 区 ， 该 成 员 很 少 用 到 ， 仅 仅 在 


12.8 节 描述 的 使 用 缓冲 区 转发 上 游 服 务 器 的 响应 时 才 使 用 了 


Shadow 成 员 ， 这 是 因为 


Nginx 太 节约 内 存 了 ， 分配 一 块 内 存 并 使 用 


ngXx_buf_t 表 示 接 收 到 的 上 游 服务 器 响应 后 ， 在 向 下 游客 户 端 转发 时 可 能 会 把 这 块 内 存 存 储 到 文件 中 ， 也 可 能 直 蔬 





Nginx 绝 不 会 重新 复制 一 份 内 存 用 于 新 的 目的 ， 而 是 再 次 建立 一 个 


ngx_buf_t 结 构 体 指向 原 内 存 ， 这 样 多 个 


ngx_buf tt 结构 体 指 向 了 同一 块 内 存 ， 它 们 之 间 的 关系 就 通过 


shadow 成 员 来 引用 。 这 种 设计 过 于 复杂 ， 通 常 不 建议 使 用 


*/ 
ngx_buf_t *shadow; 
// 临时 内 存 标志 位 ， 为 


1 时 表示 数据 在 内 存 中 且 这 段 内 存 可 以 修改 


unsigned temporary:1; 
// 标志 位 ， 为 


工时 表示 数据 在 内 存 中 且 这 段 内 存 不 可 以 被 修改 


unsigned memory:1; 
// 标志 位 ， 为 


1 时 表示 这 段 内 存 是 用 


mmap 系 统 调 用 映射 过 来 的 ， 不 可 以 被 修改 


unsigned mmap:1; 
// 标志 位 ， 为 
1 时 表示 可 回收 
unsigned recycled:1; 
// 标志 位 ， 为 


工时 表示 这 上 段 缓冲 区 处 理 的 是 文件 而 不 是 内 存 


unsigned in_file:1; 
// 标志 位 ， 为 


1 时 表示 需要 执行 


flush 操 作 


unsigned flush:1; 
/* 标 志 位 ， 对 于 操作 这 块 缓冲 区 时 是 否 使 用 同步 方式 ， 需 谨慎 考虑 ， 这 可 能 会 阻塞 


Nginx 进 程 ， 


Nginx 中 所 有 操作 几乎 都 是 异步 的 ， 这 是 它 支 持 高 并 发 的 关键 。 有 些 框 架 代 码 在 


Sync 为 


1 时 可 能 会 有 阻塞 的 方式 进行 


I/0 操 作 ， 它 的 意义 视 使 用 它 的 


Nginx 模 块 而 定 


*/ 
unsigned sync:1; 
/* 标 志 位 ， 表 示 是 否 是 最 后 一 块 缓冲 区 ， 因 为 


ngx_buf 七 可 以 由 


ngx_chain_t 链 表 串 联 起 来 ， 因 此 ， 当 


ast_buf 为 


1 时 ， 表 示 当 前 是 最 后 一 块 待 处 理 的 缓冲 区 


7 
unsigned last_buf:1; 
// 标志 位 ， 表 示 是 否 是 


ngx_chain_t 中 的 最 后 一 块 缓冲 区 


unsigned last_in_chain:1; 
/* 标 志 位 ， 表 示 是 否 是 最 后 一 个 影子 缓冲 区 ,与 


shadow 域 配合 使 用 。 通 常 不 建议 使 用 它 


*/ 
unsigned last_shadow:1; 
// 标志 位 ， 表 示 当 前 缓冲 区 是 否 属于 临时 文件 


unsigned temp_file:1; 


}; 





关于 使 用 ngx_buf_t 的 案例 参见 3.7.2 节 。ngx_buf_t 是 一 种 基本 数据 
结构 ， 本 质 上 它 提供 的 仅仅 是 一 些 指针 成 员 和 标志 位 。 对 于 HTTP 模 块 
来 说， 需要 注意 HTTP 框架、 事件 框 洪 是 如 何 设 置 和 使 用 pos、last 等 指 
针 以 及 如 何 处 理 这 些 标志 位 的 ， 上 述说 明 只 是 最 常见 的 用 法 。 如果 我 
们 目 定义 一 个 ngx_buf_t 结 构 体 ， 不 应 当 受 限于 上 述 用 法 ， 而 应 该 根据 业 
务 需求 自行 定义 。 例 如 ， 在 13.7 节 中 用 一 个 ngx_buf t 绥 冲 区 转 及 上 下 游 
TCP 流 时 ，pos 会 指向 将 要 及 送 到 下 游 的 TCP 流 起 始 地 址 ， 而 last 会 指 癌 
预备 接收 上 游 TCP 流 的 缓冲 区 起 始 地 址 。) 








3.2.6 ngx_chain_t 数 据 结构 


ngx_chain_t 是 与 ngx_buf _t 配 合 使 用 的 链表 数据 结构 ， 下 面 看 一 下 它 
的 定义 : 





typedef struct ngx_chain_s ngx_chain_t; 
struct ngx_chain_s { 

ngx_buf_t *buf; 

ngx_chain t *next; 


}; 





buf 指 同 当 前 的 ngx_buf_t 绥 冲 区 ，next 则 用 来 指 癌 下 一 个 
ngx_chain_t。 如 果 这 是 最 后 一 个 ngx_chain_t， 则 需要 把 next 置 为 


NULL. 


在 向 用 户 发 送 HITP 包 体 时 ， 就 要 传 入 ngx_chain_t 链 表 对 象 ， 注 
意 ， 如 果 是 最 后 一 个 ngx_chain_t， 那 么 必须 将 next 置 为 NULL， 否 则 永 
远 不 会 发 送 成 功 ， 而 且 这 个 请 求 将 一 直 不 会 结束 〈Nginx 框 架 的 要 
2 





3.3 如何 将 自己 的 HTTP 模块 编译 进 Nginx 


Nginx 提 供 了 一 种 简单 的 方式 将 第 三 方 的 模块 编译 到 Nginx 中 。 首 先 
把 源 代码 文件 全 部 放 到 一 个 目录 下 ， 同 时 在 该 目录 中 编写 一 个 文件 用 于 
通知 Nginx 如 何 编译 本 模块 ， 这 个 文件 名 必须 为 config。 它 的 格式 将 在 
3.3.1 市 中 说 明 。 


这 样 ， 只 要 在 configure 脚 本 执行 时 加 入 参数 --add- 
module=PATH (PATH 就 是 上 面 我 们 给 定 的 源 代码 、config 文 件 的 保存 
目录 ) ， 就 可 以 在 执行 正常 编译 安装 流程 时 完成 Nginx 编 译 工 作 。 


有 时 ，Nginx 提 供 的 这 种 方式 可 能 无 法 满足 我 们 的 需求 ， 其 实 ， 在 
执行 完 configure 脚 本 后 Nginx 会 生成 objs/Makefile 和 objs/ngx_modules.c 文 
件 ， 完 全 可 以 自己 去 修改 这 两 个 文件 ， 这 是 一 种 更 强大 也 复杂 得 多 的 方 
法 ， 我 们 将 在 3.3.3 节 中 说 明 如 何 直接 修改 它们 。 





3.3.1 ”config 文 件 的 写法 


config 文 件 其 实 是 一 个 可 执行 的 Shell 脚 本 。 如 果 只 想 开 发 一 个 HTTP 
模块 ， 那 么 config 文 件 中 需要 定义 以 下 3 个 变量 ， 


ngx_addon_name: 仅 在 configure 执 行 时 使 用 ， 一 般 设置 为 模块 名 


称 。 


. HTTP _ MODULES: 保存 所 有 的 HTTP 模 块 名 称 ， 每 个 HTTP 模 块 
间 由 空格 符 相 连 。 在 重新 设置 HTTP_MODULES 交 量 时 ， 不 要 直接 替 盖 
它 ， 因 为 configure 调 用 到 自 定义 的 config 脚 本 前 ， 已 经 将 各 个 HTTP 模 块 


设置 到 HTITIP_MODULES 变 量 中 了 ， 因 此 ， 要 像 如 下 这 样 设 置 : 





"$HTTP_MODULES ngx_http_mytest_module" 





- NGX_ADDON_SRCS: 用 于 指定 新 增 模块 的 源 代码 ， 多 个 待 纺 
译 的 源 代码 间 以 空格 符 相 连 。 注 意 ， 在 设置 NGX_ADDON_SRCS 时 可 
以 使 用 $negx_addon_dit 变 量 ， 它 等 价 于 configure 执 行 时 --add- 
module=PATH 的 PATH 参 数 。 


因此 ， 对 于 mytest 模 块 ， 可 以 这 样 编写 config 文 件 : 





ngx_addon_name=ngx_http_mytest_module 
HTTP_MODULES="$HTTP_MODULES ngx_http_mytest_module" 
NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_mytest_ module.c" 





@ 注意 “以 上 3 个 变量 并 不 是 唯一 可 以 在 config 文 件 中 自 定 义 的 部 
分 。 如 果 我 们 不 是 开发 HTTP 模块 ， 而 是 开发 一 个 HTTP 过 滤 模 块 ， 那 么 
就 要 用 HTITP_FIILTER_MODULES 替 代 上 面 的 HITP_MODULES 变 量 。 
事实 上 上， 包括 $CORE_ MODULES、$EVENT_MODULES、 


$HTTP MODULES $HTTIP_FILTER_ MODULES. 





HTIP_HEADERS_FILTER_MODULE 等 模块 变量 都 可 以 重 定 义 ， 它 们 
分 别 对 应 着 Nginx 的 核心 模块 、 事 件 模块 、HTTP 模 块 、HTTP 过 滤 模 
块 、HTTP 头 部 过 滤 模 块 。 除 了 NGX_ADDON_SRCS 变 量 ， 或 许 还 有 一 
个 变量 我 们 会 用 到 ， 即 YNGX_ADDON_DEPS 变 量 ， 它 指定 了 模块 依赖 
的 路 径 ， 同 样 可 以 在 config 中 设置 。 


3.3.2 ”利用 configure 脚 本 将 定制 的 模块 加 入 到 Nginx 中 


在 1.6 节 提 到 的 configure 执 行 流程 中 ， 其 中 有 两 行 脚本 负责 将 第 三 方 
模块 加 入 到 Nginx 中 ， 如 下 所 示 。 





. auto/modules 
. auto/make 





下 面 完整 地 解释 一 下 configure 脚 本 是 如 何 与 3.3.1 节 中 提 到 的 config 
文件 配合 起 来 把 定制 的 第 三 方 模块 加 入 到 Nginx 中 的 。 


在 执行 configure--add-module=PATH 命 令 时 ，PATH 就 是 第 三 方 模块 
所 在 的 路 径 。 在 configure 中 ， 通 过 auto/options 脚 本 设置 了 
NGX_ADDONS 变 量 : 





--add-module=*) NGX_ADDONS="$NGX_ADDONS $value" ); ， 





在 configure 命 令 执行 到 auto/modules 脚 本 时 ， 将 在 生成 的 


ngx_modules.c 文 件 中 加 入 定制 的 第 三 方 模块 。 





if test -n "$NGX_ADDONS"; then 
echo configuring additional modules 
for ngx_addon_dir in $NGX_ADDONS 


do 
echo "adding module in $ngx_addon_dir" 
if test -f $ngx_addon_dir/config; then 
# 在 这 里 执行 自 定义 的 
Config 脚 本 
, $ngx_addon_dir/config 
echo ”+ $ngx_addon name was configured" 
else 
echo "$0: error: no $ngx_addon dir/config was found" 
exit 1 
fi 
done 














可 以 看 到 ，$NGX_ADDONS 可 以 包含 多 个 目录 ， 对 于 每 个 目录 ， 
如 果 其 中 存在 config 文 件 就 会 执行 ， 也 就 是 说 ， 在 config 中 重新 定义 的 变 
量 都 会 生效 。 之 后 ，auto/modules 脚 本 开始 创建 ngx_modules.c 文 件 ， 这 
个 文件 的 关键 点 就 是 定义 了 ngx_module_t*ngx_modules[] 数 组 ， 这 个 数 
组 存储 了 Nginx 中 的 所 有 模块 。Nginx 在 初始 化 、 处 理 请 求 时 ， 都 会 循环 
访问 ngx_modules 数 组 ， 确 定 该 用 哪 一 个 模块 来 处 理 。 下 面 来 看 一 下 
auto/modules 是 如 何 生成 数组 的 ， 代 码 如 下 所 示 : 








modules="$CORE_MODULES S$EVENT_MODULES" 
if [ $USE_OPENSSL = YES ]; then 
modules="$modules $0PENSSL MODULE" 
CORE_DEPS="$CORE_DEPS S$OPENSSL_DEPS" 
CORE_ SRCS="$CORE_SRCS S$OPENSSL_SRCS" 
fi 
if [ $HTTP = YES ]; then 
modules="$modules $HTTP_MODULES $HTTP_FILTER_MODULES AN 
$HTTP_HEADERS_FILTER_MODULE \ 
$HTTP_AUX_FILTER_MODULES AN 


$HTTP_COPY_FILTER_MODULE \ 

$HTTP_RANGE_BODY_FILTER_MODULE \ 

$HTTP_NOT_MODIFIED_FILTER MODULE" 
NGX_ADDON_DEPS="$NGX_ADDON_DEPS \$(HTTP_DEPS)" 





fi 





首先 ，auto/modules 会 按 顺 序 生成 modules 变 量 。 注 意 ， 这 里 的 
$HTTP_MODULES 等 已 经 在 config 文 件 中 重 定 义 了 。 这 时 ，modules 变 
量 是 包含 所 有 模块 的 。 然 后 ， 开 始 生 成 ngx_modules.c 文 件 : 





cat << END > $NGX_MODULES_C 
#include <ngx_config.h> 

#include <ngx_core.h> 

$NGX_PRAGMA 





END 
for mod in $modules 
do 

echo "extern ngx_ module t $mod;" >> $NGX_MODULES_C 
done 
echo >> $NGX_MODULES_C 
echo 'ngx_ module t *ngx_ modules[] = 人 >> $NGX_MODULES_C 
for mod in $modules 
do 

# 向 


ngx_modules 数 组 里 添加 


Nginx 模 块 
echo " &$mod," >> $NGX_MODULES_C 
done 
cat << END >> $NGX_MODULES_C 
NULL 
}; 
END 





这 样 束 已 经 确定 了 Nginx 在 运行 时 会 调用 目 定 义 的 模块 ， 而 
auto/make 脚 本 负责 把 相关 模块 编译 进 Nginx。 


在 Makefile 中 生成 编译 第 三 方 模块 的 源 代码 如 下 : 


LE | 


if test -n "$NGX_ADDON_SRCS"; then 
ngx_cc="\$(CC) $ngx_compile_ opt \$(CFLAGS) $ngx_use_pch \$(ALL_INCS)" 
for ngx_src in $NGX_ADDON_SRCS 
do 
ngx_obj="addon/ basename \ dirname $ngx_src\  " 
ngx_obj= “echo $ngx_obj/\ basename $ngx_src\. \ 
| Sed -e "s/\// $ngx_regex_dirsep/g". 
ngx_obj= “echo $ngx_obj \ 
| sed -e 
"Ss#^\(.*\.\)cpp\\$#$ngx_objs_dir\1$ngx_objext#g" \ 
-e 
"Ss#^\(.*\.\)cc\\$#$ngx_objs_dir\1$ngx_objext#g" \ 
-e 
"S#AN(,*N.N\)cNNA$t#$ngx_objs_dirX1$ngx_objext#g"” \ 
-e 
"S#AN(.*\,.N\)SANA$t#$ngx_objs_dirX1$ngx_objext#g"” 
ngx_src= echo $ngx_src | sed -e "s/\// $ngx_regex_dirsep/g". 
cat << END >> $NGX_MAKEFILE 
$ngx_obj: \$(ADDON_DEPS)$ngx_cont$ngx_src 
$ngx_cc$ngx_tab$ngx_objout$ngx_obj$ngx_tab$ngx_src$NGX_AUX 
END 
done 
fi 





下 面 这 段 代 码 用 于 将 各 个 模块 的 目标 文件 设置 到 ngx_obj 变 量 中 ， 
紧 接着 会 生成 Makefile 里 的 链接 代码 ， 并 将 所 有 的 目标 文件 、 库 文件 链 
接 成 二 进 制程 序 。 





for ngx_src in $NGX_ADDON_SRCS 
do 
ngx_obj="addon/ basename \ dirname $ngx_SsrcN  " 
test -d $NGX_OBJS/$ngx_obj || mkdir -p $NGX_OBJS/$ngx_obj 
ngx_obj= “echo $ngx_obj/\ basename $ngx_src\. \ 
| Sed -e "s/\// $ngx_regex_ dirsep/g". 
ngx_all_srcs="$ngx_all_srcs $ngx_obj" 
done… 


cat << END >> $NGX_MAKEFILE 
$NGX_OBJS${ngx_dirsep}nginx${ngx_binext}: 
$ngx_deps$ngx_spacer \$(LINK) 
${ngx_long_start}${ngx_binout}$NGX_OBJS${ngx_dirsep}nginx$ngx_long_cont$ngx 
_objs$ngx_libs$ngx_link 
$ngx_rcc 
${ngx_long_end} 
END 


as 


综 上 可 知 ， 第 三 方 模块 束 是 这 样 丛 入 到 Nginx 程 序 中 的 。 


3.3.3 ”直接 修改 Makefile 文 件 





3.3.2 市 中 介绍 的 方法 营 无 疑问 是 最 方便 的 ， 因 为 大 量 的 工作 已 由 
Nginx 中 的 configure 脚 本 帮 我 们 做 好 了 。 在 使 用 其 他 第 三 方 模块 时 ， 一 
般 也 推荐 使 用 该 方法 。 





我 们 有 时 可 能 需要 更 灵活 的 方式 ， 比 如 重新 决定 
ngx_module_t*ngx_modules[] 数 组 中 各 个 模块 的 顺序 ， 或 者 在 编译 源 代 
码 时 需要 加 入 一 些 独特 的 编译 选项 ， 那 么 可 以 在 执行 完 configure 后 ， 对 
生成 的 objsngx_modules.c 和 objsMakefile 文 件 直接 进行 修改 。 











在 修改 objs/ngx_modules.c 时 ， 首 先 要 添加 新 增 的 第 三 方 模块 的 声 
明 ， 如 下 所 示 。 





extern ngx_ module t ngx_http_mytest_ module,; 








其 次 ， 在 合适 的 地 方 将 模块 加 入 到 ngx_modules 数 组 中 。 





ngx_module _t *ngx modules[] = { 





&ngx_http_upstream ip_hash module, 
&ngx_http_mytest_module, 
&ngx_http_write_ filter_ module, 





NULL 





注意 ， 模 块 的 顺序 很 重要 。 如 有 果 同 时 有 两 个 模块 表示 对 同一 个 请 求 
感 兴趣 ， 那 么 只 有 顺序 在 前 的 模块 会 被 调用 。 


修改 objs/Makefile 时 需要 增加 编译 源 代 码 的 部 分 ， 例 如 : 





objs/addon/httpmodule/ngx_http_mytest_ module.o: $(ADDON_DEPS) \\ 
../sample/httpmodule// ngx_http_mytest_ module.c 
$(CC) -c $(CFLAGS) $(ALL_INCS) \ 
-0 objs/addon/httpmodule/ngx_http_mytest_ module.o \ 
../sample/httpmodule// ngx_http_mytest_module,c 








还 需要 把 目标 文件 链接 到 Nginx 中 ， 例 如 : 





objs/nginx: objs/src/core/nginx.o \ 


objs/addon/httpmodule/ngx_http_mytest module.o \ 
objs/ngx_modules.o 
$(LINK) -0o objs/nginx \ 
objs/src/core/nginx.o \ 


objs/addon/httpmodule/ngx_http_mytest_module.o \ 
objs/ngx_modules.o \ 
-lpthread -lcrypt -lpcre -lcrypto -lcrypto -1z 





请 慎 用 这 种 直接 修改 Makefile 和 ngx_modules.c 的 方法 ， 不 正确 的 修 
改 可 能 导致 Nginx 工 作 不 正常 。 


3.4 HTTP 模 块 的 数据 结构 





定义 HTTP 模 块 方式 很 简单 ， 例 如 : 





ngx_module_t ngx_http_mytest_module; 








其 中 ，ngx_module t 是 一 个 Nginx 模 块 的 数据 结构 ( 详 见 8.2 节 )。 
下 面 来 分 析 一 下 Nginx 模 块 中 所 有 的 成 员 ， 如 下 所 示 : 





typedef struct ngx_ module_s ngx_module_t; 
struct ngx_module s { 
/* 下 面 的 


ctXx_index、 


IndexX、 


spareg、 


spare1、 


Spare2、 


spare3、 


Version 交 量 不 需要 在 定义 时 赋值 ， 可 以 用 


Nginx 准 备 好 的 宏 


NGX_MODULE_V1 来 定义 ， 它 已 经 定义 好 了 这 


7 个 值 。 


#define NGX_MODULE_V1 0, 0, 0, 0, 0, 0, 1 
对 于 一 类 模块 (由 下 面 的 


type 成 员 决 定 类 别 ) 而 言 ， 


ctx_index 表 示 当 前 模块 在 这 类 模块 中 的 序号 。 这 个 成 员 常 常 是 由 管理 这 类 模块 的 一 个 


Nginx 核 心 模 块 设置 的 ， 对 于 所 有 的 


HTTP 模 块 而 言 ， 


Ctx_index 是 由 核心 模块 


ngx_http_module 设 置 的 。 


Ctx_index 非 常 重要 ， 


Nginx 的 模块 化 设计 非常 依赖 于 各 个 模块 的 顺序 ， 它 们 既 用 于 表达 优先 级 ， 也 用 于 表明 每 个 模块 的 位 置 ， 借 以 帮助 


Nginx 框 架 快速 获得 茶 个 模块 的 数据 ( 


HTTP 框 架设 置 


Ctx_index 的 过 程 参见 


10.7 节 ) 

WA 
ngx_uint_t ctx_index; 
/*index 表 示 当 前 模块 在 


ngx_modules 数 组 中 的 序号 。 注 意 ， 


Ctx_index 表 示 的 是 当前 模块 在 一 类 模块 中 的 序号 ,而 


index 表 示 当 前 模块 在 所 有 模块 中 的 序号 ， 它 同样 关键 。 


Nginx 启 动 时 会 根据 


ngx_modules 数 组 设置 各 模块 的 


index 值 。 例 如 : 


ngx_max_module = 0; 
for (i = 0; ngx_ modules[i]; i++) { 
ngx_modules[i]->index = ngx_max_module++; 


} 
4 

ngx_uint_t index; 

// Spare 系 列 的 保留 变量 ， 暂 未 使 用 

ngx_uint_t spare0; 

ngx_uint_t sparel,; 

ngx_uint_t spare2,; 

ngx_uint_t spare3,; 

// 模块 的 版 本 ， 便于 将 来 的 扩展 。 目前 只 有 一 种 ， 默 认为 
工 


ngx_uint_t version; 
/*Ctx 用 于 指向 一 类 模块 的 上 下 文 结构 体 ， 为 什么 需要 


Ctx 呢 ?因为 前 面 说 过 ， 





Nginx 模 块 有 许多 种 类 ， 不 同类 模块 之 间 的 功能 差别 很 大 。 例 如 ， 事 件 类 型 的 模块 主要 处 理 


I/0 事 件 相 关 的 功能 ， 


HTTP 类 型 的 模块 主要 处 理 


HTTP 应 用 层 的 功能 。 这 样 ， 每 个 模块 都 有 了 自己 的 特性 


CtX 将 会 指向 特定 类 型 模块 的 公共 接口 。 例 如 ， 在 


HTTP 模 块 中 ， 


CtX 需 要 指向 


ngx_http_module tt 结构 体 


*/ 
void “OEX; 
// commands 将 处 理 


nginx.conf 中 的 配置 项 ， 详 见 第 


ngx_command_t *commands; 
/*type 表 示 该 模块 的 类 型 ， 它 与 


CtX 指 针 是 紧密 相关 的 。 在 官方 


Nginx 中 ， 它 的 取 值 范围 是 以 下 


5 种 : 


NGX_HTTP_MODULE、 


NGX_CORE_MODULE、 


NGX_CONF_MODULE、 


NGX_EVENT_MODULE、 


NGX_MAIL _MODULE。 这 


5 种 模块 间 的 关系 参考 图 


8-2。 实 际 上 ， 还 可 以 自 定义 新 的 模块 类 型 


4 
ngx_uint_t type; 
/* 在 


Nginx 的 启动 、 停 止 过 程 中 ， 以 下 


7 个 函数 指针 表示 有 


7 个 执行 点 会 分 别 调用 这 


7 种 方法 (参见 


8.4 节 ~ 


8.6 节 ) 。 对 于 任 一 个 方法 而 言 ， 如 果 不 需要 


Nginx 在 菜 个 时 刻 执行 它 ， 那 么 简单 地 把 它 设 为 


NULL 空 指针 即 可 


be4 
/* 虽 然 从 字面 上 理解 应 当 在 


master 进 程 启动 时 回调 


init_master, 但 到 目前 为 止 ， 框架 代码 从 来 不 会 调用 它 ， 因 此 ， 可 将 





init_master 设 为 


NULL */ 
ngx_int_t (*init_ master)(ngx_ log t *10g); 
A/*init_module 回 调 方法 在 初始 化 所 有 模块 时 被 调用 。 在 


master/worker 模 式 下 ， 这 个 阶段 将 在 启动 


worker 子 进程 前 完成 


*/ 
ngx_int_t (*init_ module)(ngx_cycle t *cycle); 
/* init_process 回 调 方 法 在 正常 服务 前 被 调用 。 在 


master/worker 模 式 下 ， 多 个 


Worker 子 进程 已 经 产生 ， 在 每 个 


worker 进 程 的 初始 化 过 程 会 调用 所 有 模块 的 


init_process 函 数 


< 
ngx_int_t (*init_process)(ngx_cycle t *cycle); 
/” 由 于 


Nginx 暂 不 支持 多 线程 模式 ， 所 以 


init_thread 在 框架 代码 中 没有 被 调用 过 ， 设 为 


NULL*/ 
ngx_int_t (*init_thread)(ngx_cycle _t *cycle); 
XW/ 辣 旦 ; 


eXit_thread 也 不 支持 ， 设 为 


NULL 
void (*exit_ thread)(ngx_cycle t *cycle); 
/* exit_process 回 调 方法 在 服务 停止 前 调用 。 在 


master/worker 模 式 下 ， 


worker 进 程 会 在 退出 前 调用 它 


* 
/ 
void (*exit_process)(ngx_cycle t *cycle); 
// ”exit_master 回 调 方法 将 在 


master 进 程 退 出 前 被 调用 


void (*exit master)(ngx_cycle t *cycle); 
Ar* 以 下 


8 个 


Spare_hook 变 量 也 是 保留 字段 ， 目 前 没有 使 用 ， 但 可 用 


Nginx 提 供 的 


NGX_MODULE_V1_PADDING 宏 来 填充 。 看 一 下 该 宏 的 定义 : 


#define NGX MODULE V1 PADDING 0, 0, 90, 0, 0, 0, 0, 0*/ 


uintptr_t spare_hookoO; 
uintptr_t spare_hooki1; 
uintptr_t spare_hook2; 
uintptr_t spare_hook3; 
uintptr_t spare_hook4; 
uintptr_t spare_hooks; 
uintptr_t spare_hook6; 
uintptr_t spare_hook7; 


}; 








定义 一 个 HTTP 模 块 时 ， 务 必 把 type 字 段 设 为 NGX_HTTP_MODULE。 




















日 它 们 的 古 





对 于 下 列 回调 方法 : init module、init process、exit_process、exit_master， 调 月 


定义 HTTP 模 块 时 ， 最 重要 的 是 要 设置 ctx 和 commands 这 两 个 成 员 。 对 于 HTTP 类 型 的 模 





HTTP 框架 在 读 取 、 重 载 配置 文件 时 定义 了 由 ngx_http_module_t 接 口 描述 的 8 个 阶段 ，HI 





typedef Struct { 
// 解析 配置 文件 前 调用 


ngx_int_t (*preconfiguration)(ngx_conf_t *cf); 


// 完成 配置 文件 的 解析 后 调用 


ngx_int_t (*postconfiguration)(ngx_conf_t *cf); 


/* 当 需要 创建 数据 结构 用 于 存储 
main 级 别 (直属 于 
http{...} 块 的 配置 项 ) 的 全 局 配置 项 时 ， 可 以 通过 


create_main_conf 回 调 方法 创建 存储 全 局 配置 项 的 结构 体 


2 
void *(*create main_ conf)(ngx_conf_t *cf); 


// 常用 于 初始 化 
main 级 别 配 置 项 


char *(*init_ main_conf)(ngx_conf_t *cf, void *conf); 


/* 当 需要 创建 数据 结构 用 于 存储 
srv 级 别 ( 直 属于 虚拟 主机 
server{...} 块 的 配置 项 ) 的 配置 项 时 ， 可 以 通过 实现 
create_srv_conf 回 调 方法 创建 存储 


srv 级 别 配置 项 的 结构 体 


* 
/ 
void *(*create_ srv_conf)(ngx_conf_t *cf); 
// ”merge_srv_conf 回 调 方法 主要 用 于 合并 


main 级 别 和 


srv 级 别 下 的 同名 配置 项 


char *(*merge_srv_conf)(ngx_conf_t *cf, void *prev, void *conf); 


/* 当 需要 创建 数据 结构 用 于 存储 


loc 级 别 ( 直 属于 

location{...} 块 的 配置 项 ) 的 配置 项 时 ， 可 以 实现 
create_loc_conf 回 调 方 法 

*/ 


void *(*create_ loc_conf)(ngx_conf_t *cf); 
// merge_loc_conf 回 调 方法 主要 用 于 合并 


srv 级 别 和 


loc 级 别 下 的 同名 配置 项 


char *(*merge_loc_conf)(ngx_conf_t *cf, void *prev, void *conf); 
} ngx_http_module_t; 








不 过 ， 这 8 个 阶段 的 调用 顺序 与 上 述 定义 的 顺序 是 不 同 的 。 在 Nginx 启 动 过 程 中 ，HTTP 刘 








1) create main conf 


2) create_srv_conf 


3) create_loc_conf 


4) preconfiguration 


5) init main conf 


6) merge_srv_conf 


7) merge loc_conf 


8) postconfiguration 





commands 数 组 用 于 定义 模块 的 配置 文件 参数 ， 每 一 个 数组 元 素 都 是 ngx_command t 类 型 





typedef struct ngx_command_s ngx_command_t; 
struct ngx_command_s { 


// 配置 项 名 称 ， 如 


"gzip" 
ngx_str_t name; 


/* 配 置 项 类 型 ， 
type 将 指定 配置 项 可 以 出 现 的 位 置 。 例 如 ， 出 现在 
server{} 或 
location{} 中 ， 以 及 它 可 以 携带 的 参数 个 数 


*y 
ngx_uint_t type; 
// 出 现 了 


name 中 指定 的 配置 项 后 ， 将 会 调用 


set 方 法 处 理 配 置 项 的 参数 


char *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf); 


// 在 配置 文件 中 的 偏 移 量 


ngx_uint_t conf; 


/* 通 常用 于 使 用 预 设 的 解析 方法 解析 配置 项 ， 这 是 配置 模块 的 一 个 优秀 设计 。 它 需要 与 
conf 配 合 使 用 ， 在 第 


4 章 中 详细 介绍 


2 
ngx_uint_t offset; 


// 配置 项 读 取 后 的 处 理 方法 ， 必 须 是 


ngx_conf_post_t 结 构 的 指针 


void *post; 


ngx_null _ command 只 是 一 个 空 的 ngx_command t， 如 下 所 示 : 





#define ngx_null command { ngx_null_string, 0, NULL, 0, 0, NULL } 





3.5 定义 自己 的 HTTP 模 块 


上 文中 我 们 了 解 了 定义 HITP 模 块 时 需要 定义 哪些 成 员 以 及 实现 哪 
些 方法 ， 但 在 定义 HTTP 模 块 前 ， 首 先 需 要 确定 自 定义 的 模块 应 当 在 什 
么 样 的 场景 下 开始 处 理 用 户 请 求 ， 也 就 是 说 ， 先 要 弄 清楚 我 们 的 模块 是 
如 何 介 入 到 Nginx 处 理 用 户 请 求 的 流程 中 的 。 从 2.4 节 中 的 HTTP 配 置 项 
意义 可 知 ， 一 个 HTTP 请 求 会 被 许多 个 配置 项 控制 ， 实 际 上 这 是 因为 一 
个 HTTP 请 求 可 以 被 许多 个 HTTP 模 块 同时 人 处理。 这 样 一 来 ， 肯 定 会 有 一 
个 先后 问题 ， 也 就 是 说 ， 谁 先 处 理 请 求 谁 的 “权力 ”就 更 大 。 例 如 ， 
ngx_http_access_module 模 块 的 deny 选 项 一 旦 得 到 满足 后 ，Nginx 就 会 决 
定 拒绝 来 自 某 个 IP 的 请 求 ， 后 面 的 诸如 root 这 种 访问 静态 文件 的 处 理 方 
式 是 得 不 到 执行 的 。 另 外 ， 由 于 同一 个 配置 项 可 以 从 属于 许多 个 
server、location 配 置 块 ， 那 么 这 个 配置 项 将 会 针对 不 同 的 请 求 起 作用 。 
因此 ， 现 在 面临 的 问题 是 ， 我 们 希望 自己 的 模块 在 哪个 时 刻 开 始 处 理 请 
求 ? 是 希望 自己 的 模块 对 到 达 Nginx 的 所 有 请 求 都 起 作用 ， 还 是 希望 只 
对 某 一 类 请 求 〈 如 URI 匹 配 了 location 后 表达 式 的 请 求 ) 起 作用 ? 

















Nginx 的 HTTP 框架 定义 了 非常 多 的 用 法 ， 我 们 有 很 大 的 自由 来 定义 
自己 的 模块 如 何 介入 HTTP 请 求 的 处 理 ， 但 本 章 只 想 说 明 最 简单 、 最 常 
见 的 HTTP 模块 应 当 如 何 编号， 因此 ， 我 们 这 样 定义 第 一 个 HITP 模 块 介 
入 Nginx 的 方式 : 





1) 不 希望 模块 对 所 有 的 HITP 请 求 起 作用 。 


2) 在 nginx.conf 文 件 中 的 http{}、server{} 或 者 location{} 块 内 定义 
mytest 配 置 项 ， 如 果 一 个 用 户 请 求 通过 主机 域名 、URI 等 匹配 上 了 相应 
的 配置 块 ， 而 这 个 配置 块 下 又 具有 mytest 配 置 项 ， 那 么 希望 mytest 模 块 
开始 处 理 请 求 。 











在 这 种 介入 方式 下 ， 模 块 处 理 请 求 的 顺序 是 固定 的 ， 即 必须 在 
HTTP 框 架 定 义 的 NGX_HTTP_ CONTENT_PHASE 阶 段 开 始 处 理 请 求 ， 
具体 内 容 下 文 详 述 。 








下 面 开 始 按照 这 种 方式 定义 mytest 模 块 。 首 先 ， 定 义 mytest 配 置 项 
的 处 理 。 从 上 文中 关于 ngx_command_t 结 构 的 说 明 来 看 ， 只 需要 定义 一 
个 ngx_command t 数 组 ， 并 设置 在 出 现 mytest 配 置 后 的 解析 方法 由 
ngx_http_mytest“ 担 当 ”， 如 下 所 示 : 





static ngx_command t ngx_http mytest commands[] = { 
{ ngx_string("mytest"), 

NGX_HTTP_MAIN_CONF |NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_HTTP_LMT_CONF|NGX_( 

ngx_http_mytest, 

NGX_HTTP_LOC_CONF_OFFSET, 

0, 
NULL 
ngx_null command 











大 


其 中 ，ngx_http_mytest 是 ngx_command_t 结 构 体 中 的 set 成 员 ( 完 整 


定义 为 char*(*set)(ngx_conf _t*cf,ngx_command_t*cmd,void*conf);〉， 当 


在 某 个 配置 块 中 出 现 mytest 配 置 项 时 ，Nginx 将 会 调用 ngx_http_mytest 方 


法 。 下 面 看 一 下 如 何 实现 ngx_http_mytest 方 法 。 





static char * 
ngx_http_mytest(ngx_conf_t *cf, ngx_command t *cmd, void *conf) 


ngx_http_core_loc conf_t *clcf; 


/* 首 先 找到 





mytest 配 置 项 所 属 的 配置 块 ， 


Clcf 看 上 去 像 是 


location 块 内 的 数据 结构 ， 其 实 不 然 ， 它 可 以 是 


main、 


SrV 或 者 


loc 级 别 配置 项 ， 也 就 是 说 ， 在 每 个 


http{} 和 


Server{} 内 也 都 有 一 个 


ngx_http_core_loc_conf_t 结 构 体 





*/ 
clcf = ngx_http_conf_get_ module loc conf(cf, ngx_http_core module); 
A/*HTTP 框 架 在 处 理 用 户 请 求 进行 到 





NGX_HTTP_CONTENT_PHASE 阶 段 时 ， 如 果 请 求 的 主机 域名 、 


URI 与 


mytest 配 置 项 所 在 的 配置 块 相 匹配 ， 就 将 调用 我 们 实现 的 


ngx_http_mytest_handler 方 法 处 理 这 个 请 求 


*% 
clcf->handler = ngx_http_mytest_handler,; 
return NGX_CONF_OK, 


当 Nginx 接 收 完 HITP 请 求 的 头 部 信息 时 ， 就 会 调用 HTTP 框 架 处 理 
请 求 ， 另 外 在 11.6 节 描述 的 NGX_HTTP_CONTENT PHASE 阶段 将 有 可 
能 调用 mytest 模 块 处 理 请 求 。 在 ngx_http_mytest 方 法 中 ， 我 们 定义 了 请 
求 的 处 理 方法 为 ngx_http_mytest_handler， 举 个 例子 来 说 ， 如 果 用 户 的 
请 求 URI 是 /test/example， 而 在 配置 文件 中 有 这 样 的 location 块 : 





Location /test { 
mytest; 





那么 ，HTTP 框 架 在 NGX_HTTP_CONTENT_PHASE 阶 段 就 会 调用 
到 我 们 实现 的 ngx_http_mytest_handler 方 法 来 处 理 这 个 用 户 请 求 。 事 实 
上 上 ，HTTP 框 架 共 定义 了 11 个 阶段 (第 三 方 HTTP 模 块 只 能 介入 其 中 的 7 
个 阶段 处 理 请 求 ， 详 见 10.6 节 ) ， 本 章 只 关注 
NGX_HTTP_CONTENT_PHASE 处 理 阶段 ， 多 数 HTTP 模 块 都 在 此 阶段 
实现 相关 功能 。 下 面 简 单 说 明 一 下 这 11 个 阶段 。 





typedef enum { 
// 在 接收 到 完整 的 


HTTP 头 部 后 处 理 的 


HTTP 阶 段 


NGX_HTTP_POST_READ_PHASE = 0, 
/* 在 还 没有 查询 到 





URI 匹 配 的 


Jocation 前 ， 这 时 


rewrite 重 写 


URL 也 作为 一 个 独立 的 


HTTP 阶 段 


3 
NGX_HTTP_SERVER_REWRITE_PHASE， 
/* 根 据 


URI 了 寻找 匹配 的 


Location， 这 个 阶段 通常 由 


ngx_http_core_module 模 块 实现 ， 不 建议 其 他 


HTTP 模 块 重新 定义 这 一 阶段 的 行为 





4 





NGX_HTTP_FIND_CONFIG_PHASE, 
/* 在 


NGX_HTTP_FIND_CONFIG_PHASE 阶 段 之 后 重 





eh 
加 





URL 的 意义 与 


NGX_HTTP_SERVER_REWRITE_PHASE 阶 段 显 然 是 不 同 的， 


location 块 ( 


location 是 与 


URI 进 行 匹 配 的 ) 


*] 
NGX_HTTP_REWRITE_PHASE, 
/* 这 一 阶段 是 用 于 在 
rewrite 重 写 





URL 后 重新 跳 到 


因为 这 两 者 会 导致 查找 到 不 同 的 





NGX_HTTP_FIND_CONFIG_PHASE 阶 段 ， 找 到 与 新 的 





URI 匹 配 的 


location。 所 以 ， 这 一 阶段 是 无 法 由 第 三 方 


HTTP 模 块 处 理 的 ， 而 仅 由 


ngx_http_core_module 模 块 使 用 


*/ 
NGX_HTTP_POST_REWRITE_PHASE, 
// 处 理 


NGX_HTTP_ACCESS_PHASE 阶 段 前 ， 


HTTP 模 块 可 以 介入 的 处 理 阶 段 


NGX_HTTP_PREACCESS_PHASE, 
A* 这 个 阶段 用 于 让 


HTTP 模 块 判断 是 否 允 许 这 个 请 求 访问 


Nginx 服 务 器 


NGX_HTTP_ACCESS_PHASE, 
/* 当 


NGX_HTTP_ACCESS_PHASE 阶 段 中 


HTTP 模 块 的 


handler 处 理 方法 返回 不 允许 访问 的 错误 码 时 (实际 是 


NGX_HTTP_FORBIDDEN 或 者 


NGX_HTTP_UNAUTHORIZED) ， 这 个 阶段 将 负责 构造 拒绝 服务 的 用 户 响应 。 所 以 ， 这 个 阶段 实际 上 用 于 给 


NGX_HTTP_ACCESS_PHASE 阶 段 收 尾 


7/ 
NGX_HTTP_POST_ACCESS_PHASE, 
/这 个 阶段 完全 是 为 了 





try_files 配 置 项 而 设立 的 。 当 


HTTP 请 求 访问 静态 文件 资源 时 ， 


try_files 配 置 项 可 以 使 这 个 请 求 顺序 地 访问 多 个 静态 文件 资源 ， 如 果 某 一 次 访问 失败 ， 则 继续 访问 


try_files 中 指定 的 下 一 个 静态 资源 。 另 外 ， 这 个 功能 完全 是 在 


NGX_HTTP_TRY_FILES_PHASE 阶 段 中 实现 的 





Wy 
NGX_HTTP_TRY_FILES_PHASE, 
// 用 于 处 理 





HTTP 请 求 内 容 的 阶段 ， 这 是 大 部 分 


HTTP 模 块 最 喜欢 介入 的 阶段 


NGX_HTTP_CONTENT_PHASE， 
/* 处 理 完 请 求 后 记录 日 志 的 阶段 。 例 如 ， 


ngx_http_log_module 模 块 就 在 这 个 阶段 中 加 入 了 一 个 


handler 处 理 方 法 ， 使 得 每 个 


HTTP 请 求 处 理 完 毕 后 会 记录 


access_10g 日 志 


*/ 
NGX_HTTP_LOG_PHASE 
} ngx_http_phases 





当然 ， 用 户 可 以 在 以 上 11 个 阶段 中 任意 选择 一 个 阶段 让 mytest 模 块 
介入 ， 但 这 需要 学 习 完 第 10 章 、 第 11 章 的 内 容 ， 完 全 熟悉 了 HTTP 框 架 





的 处 理 流程 后 才 可 以 做 到 。 


暂且 不 管 如 何 实现 处 理 请 求 的 ngx_http_mytest_handler 方 法 ， 如 果 
没有 什么 工作 是 必须 在 HITP 框 架 初始 化 时 完成 的 ， 那 就 不 必 实 现 
ngx_http_module_t 的 8 个 回调 方法 ， 可 以 像 下 面 这 样 定义 
ngx_http_module_t 接 口 。 





static ngx_http_module t ngx_http_mytest module ctx = { 





NULL， /* preconfiguration */ 

NULL， /* postconfiguration */ 

NULL， /* create main configuration */ 
NULL， /* init main configuration */ 

NULL， /* create server configuration */ 
NULL， /* merge Server configuration */ 
NULL， /* create location configuration */ 
NULL /* merge location configuration */ 


}; 





最 后 ， 定 义 mytest 模 块 : 





ngx_module t ngx_http_mytest module = { 
NGX_MODULE_V1, 








&ngx_http_mytest_ module_ctx, /* module context */ 
ngx_http_mytest_commands, /* module directives */ 
NGX_HTTP_MODULE， /* module type */ 

NULL, /* init master */ 

NULL, /* init module */ 

NULL， /* init process */ 
NULL, /* init thread */ 

NULL, /* exit thread */ 

NULL， /* exit process */ 
NULL, /* exit master */ 


NGX_MODULE_V1_PADDING 
}; 





这 样 ，mytest 模 块 在 编译 时 将 会 被 加 入 到 ngx_modules 全 局 数组 中 。 
Nginx 在 启动 时 ， 会 调用 所 有 模块 的 初始 化 回调 方法 ， 当 然 ， 这 个 例子 
中 我 们 没有 实现 它们 《也 没有 实现 HTTP 框 架 初 始 化 时 会 调用 的 


ngx_http_module t 中 的 8 个 方法 ) 。 


3.6 ”处 理 用 户 请 求 


本 节 介 绍 如 何 处 理 一 个 实际 的 HTTP 请 求 。 回 顾 一 下 上 文 ， 在 出 现 
mytest 配 置 项 时 ，ngx_http_mytest 方 法 会 被 调用 ， 这 时 将 
ngx_http_core_loc_conf t 结 构 的 handler 成 员 指定 为 
ngx_http_mytest_handler， 另 外 ，HTTP 框 架 在 接收 完 HITTP 请 求 的 头 部 
后 ， 会 调用 handler 指 向 的 方法 。 下 面 看 一 下 handler 成 员 的 原型 
ngx_http_handler_pt: 





typedef ngx_int_t (*ngx_http_handler_pt)(ngx_http_request t *r); 





从 上 面 这 段 代 码 可 以 看 出 ， 实 际 处 理 请 求 的 方法 
ngx_http_mytest_handler 将 接收 一 个 ngx_http_request_t 类 型 的 参数 r， 返 
回 一 个 ngx_int_t (参见 3.2.1 节 ) 类 型 的 结果 。 下 面 先 探讨 一 下 
ngx_http_mytest_handler 方 法 可 以 返回 什么 ， 再 看 一 下 参数 r 包 含 了 哪些 
Nginx 已 经 解析 完 的 用 户 请 求 信息 。 





3.6.1 ”处 理 方法 的 返回 值 


返回 值 可 以 是 HTTP 中 啊 应 包 的 返回 码 ， 其 中 包括 了 HTTP 框 架 
己 经 在 /src/http/ngx_http_request.h 文 件 中 定义 好 的 宏 ， 如 下 所 示 。 





#define NGX_HTTP_OK 200 








#define NGX_HTTP_CREATED 201 
#define NGX_HTTP_ACCEPTED 202 
#define NGX_HTTP_NO_CONTENT 204 
#define NGX_HTTP_PARTIAL_CONTENT 206 
#define NGX_HTTP_SPECIAL_RESPONSE 300 
#define NGX_HTTP_MOVED_PERMANENTLY 301 
#define NGX_HTTP_MOVED_TEMPORARILY 302 
#define NGX_HTTP_SEE_OTHER 303 
#define NGX_HTTP_NOT_MODIFIED 304 
#define NGX_HTTP_TEMPORARY_REDIRECT 307 
#define NGX_HTTP_BAD_REQUEST 400 
#define NGX_HTTP_UNAUTHORIZED 401 
#define NGX_HTTP_FORBIDDEN 403 
#define NGX_HTTP_NOT_FOUND 404 
#define NGX_HTTP_NOT_ALLOWED 405 
#define NGX_HTTP_REQUEST_TIME_OUT 408 
#define NGX_HTTP_CONFLICT 409 
#define NGX_HTTP_LENGTH_REQUIRED 411 
#define NGX_HTTP_PRECONDITION_FAILED 412 
#define NGX_HTTP_REQUEST_ENTITY_TOO_LARGE 413 
#define NGX_HTTP_REQUEST_URI_TOO_LARGE 414 
#define NGX_HTTP_UNSUPPORTED_MEDIA_TYPE 415 
#define NGX_HTTP_RANGE_NOT_SATISFIABLE 416 
/* The special code to close connection without any response */ 
#define NGX_HTTP_CLOSE 444 
#define NGX_HTTP_NGINX_CODES 494 
#define NGX_HTTP_REQUEST_HEADER_TOO_LARGE 494 
#define NGX_HTTPS_CERT_ERROR 495 
#define NGX_HTTPS_NO_CERT 496 
#define NGX_HTTP_TO_HTTPS 497 
#define NGX_HTTP_CLIENT_CLOSED_REQUEST 499 
#define NGX_HTTP_INTERNAL_SERVER_ERROR 500 
#define NGX_HTTP_NOT_IMPLEMENTED 501 
#define NGX_HTTP_BAD_GATEWAY 502 
#define NGX_HTTP_SERVICE_UNAVAILABLE 503 
#define NGX_HTTP_GATEWAY_TIME_OUT 504 
#define NGX_HTTP_INSUFFICIENT_STORAGE 507 





@ 注意 以 上 返回 值 除 了 RFC2616 规 范 中 定义 的 返回 码 外 ， 还 有 
Noginx 自 身 定义 的 HTTP 返 回 码 。 例 如 ，NGX_HTTP_CLOSE 就 是 用 于 要 
求 HTTP 框 架 直 接 关闭 用 户 连 接 的 。 


在 ngx_http_mytest_handler 的 返回 值 中 ， 如 有 果 是 正常 的 HTTP 返 回 
人 码 ，Nginx 承 会 按照 规范 构造 合法 的 啊 应 包 发 送 给 用 户 。 例 如 ， 假 设 对 
于 PUT 方法 暂 不 文 持 ， 那 么 ， 在 处 理 方法 中 发 现 方法 名 是 PUT 时 ， 








NGX_HTTP NOT_ALLOWED， 这 样 Nginx 也 就 会 构造 类 似 下 面 的 响应 
包 给 用 户 。 





http/1.1 405 Not Allowed 

Server: nginx/1.0.14 

Date: Sat, 28 Apr 2012 06:07:17 GMT 
Content-Type: text/html 

Content-Length: 173 

Connection: keep-alive 

<html> 

<head><title>405 Not Allowed</title></head> 
<body bgcolor="white"> 

<center><h1>405 Not Allowed</h1i></center> 
<hr><center>nginx/1.0.14</center> 

</body> 

</html> 





在 处 理 方法 中 除了 返回 HTTP 响 应 码 外 ， 还 可 以 返回 Nginx 全 局 定义 
的 几 个 错误 码 ， 包 括 : 





#define NGX_OK 
#define NGX_ERROR 
#define NGX_AGAIN 
#define NGX_BUSY 
#define NGX_DONE 
#define NGX_DECLINED 
#define NGX_ABORT 


RE 
ONPPoO 





这 些 错误 码 对 于 Nginx 自 身 提供 的 大 部 分 方法 来 说 都 是 通用 的 。 所 
以 ， 当 我 们 最 后 调用 ngx_http_output_filter (参见 3.7 节 〉 向 用 户 发 送 响 
应 包 时 ， 可 以 将 ngx_http_output_filter 的 返回 值 作为 
ngx_http_mytest_handler 方 法 的 返回 值 使 用 。 例 如 : 





static ngx_int_t ngx_http_mytest_handler(ngx_http_request t *r) 
{ 





ngx_int_t rc = ngx_http_send_header(r); 
if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) { 
return rc; 


} 
return ngx_http_output_filter(r, &out); 


} 








当然 ， 直 接 返 回 以 上 7 个 通用 值 也 是 可 以 的 。 在 不 同 的 场景 下 ， 这 7 
个 通用 返回 值 代表 的 含义 不 尽 相 同 。 在 mytest 的 例子 中 ，HTTP 框 架 在 
NGX_HTTP_CONTENT_PHASE 阶 段 调用 ngx_http_mytest_handler 后 ， 
会 将 ngx_http_mytest_handler 的 返回 值 作为 参数 传 给 
ngx_http_finalize_request 方 法 ， 如 下 所 示 。 





if (r->content_handler) { 
r->write_event_handler = ngx_http_redquest_empty_handler ; 
ngx_http_finalize_request(r, r->content_handler(r)); 
return NGX_OK; 





上 面 的 r->content_handler 会 指向 ngx_http_mytest_handler 处 理 方法 。 
也 就 是 说 ， 事 实 上 ngx_http_finalize_request 决 定 了 
ngx_http_mytest_handler 如 何 起 作用 。 本 章 不 探讨 
ngx_http_finalize_request 的 实现 〈 详 见 11.10 节 ) ， 只 简单 地 说 明 一 下 4 个 
通用 返回 码 ， 男 外 ， 在 11.10 节 中 介绍 这 4 个 返回 码 引 友 的 Nginx 一 系列 
动作 。 


. NGX_OK: 表示 成 功 。Noginx 将 会 继续 执行 该 请 求 的 后 续 动作 
(如 执行 subrequest 或 撤销 这 个 请 求 ) 。 


. NGX_DECLINED: 继续 在 NGX_HTTP_CONTENT_PHASE 阶 段 
寻找 下 一 个 对 于 该 请 求 感 兴趣 的 HTTP 模块 来 再 次 处 理 这 个 请 求 。 


.NGX_DONE: 表示 到 此 为 止 ， 同 时 HTTP 框 架 将 暂时 不 再 继续 
执行 这 个 请 求 的 后 续 部 分 。 事 实 上 ， 这 时 会 检查 连接 的 类 型 ， 如 果 是 
keepalive 类 型 的 用 户 请 求 ， 就 会 保持 住 HITP 连 接 ， 然 后 把 控制 权 交 给 
Nginx。 这 个 返回 码 很 有 用 ， 考 虑 以 下 场景 : 在 一 个 请 求 中 我 们 必须 访 
问 一 个 耗 时 极 长 的 操作 〈 比 如 某 个 网 络 调用 ) ， 这 样 会 阻塞 住 Nginx， 
又 因为 我 们 没有 把 控制 权 交 还 给 Nginx， 而 是 在 ngx_http_mytest_handler 
中 让 Nginx wotker 进 程 休眠 了 (如 等 待 网 络 的 回 包 ) ， 所 以 ， 这 就 会 导 
致 Nginx 出 现 性 能 问题 ， 该 进程 上 的 其 他 用 户 请 求 也 得 不 到 响应 。 可 如 
果 我 们 把 这 个 耗 时 极 长 的 操作 分 为 上 下 两 个 部 分 (就 像 Linux 内 核 中 对 
中 断 处 理 的 划分 ) ， 上 半 部 分 和 下 半 部 分 都 是 无 阻塞 的 〈 耗 时 很 少 的 操 
作 ) ， 这 样 ， 在 ngx_http_mytest_handler 进 入 时 调用 上 半 部 分 ， 然 后 返回 
NGX_DONE， 把 控制 交还 给 Nginx， 从 而 让 Nginx 继 续 处 理 其 他 请 求 。 
在 下 半 部 分 被 触发 时 (这 里 不 探讨 具体 的 实现 方式 ， 事 实 上 使 用 
upstream 方 式 做 反 向 代理 时 用 的 就 是 这 种 思想 ) ， 再 回调 下 半 部 分 处 理 
方法 ， 这 样 就 可 以 保证 Nginx 的 高 性 能 特性 了 。 如 果 需 要 彻底 了 解 
NGX_DONE 的 意义 ， 那 么 必须 学 习 第 11 章 内 容 ， 其 中 还 涉及 请 求 的 引 


用 计数 内 容 。 


. NGX_ERROR: 表示 错误 。 这 时 会 调用 ngx_http_terminate_request 
终止 请 求 。 如 果 还 有 POST 子 请 求 ， 那 么 将 会 在 执行 完 POST 请 求 后 再 终 
止 本 次 请 求 。 


3.6.2 ”获取 URI 和 参数 


请 求 的 所 有 信息 (如 方法 、URI、 协 议 版 本 号 和 头 部 等 都 可 以 在 
传 入 的 ngx_http_request_t 类 型 参数 r 中 取得 。ngx_http_request_t 结 构 体 的 
内 容 很 多 ， 本 节 不 会 探讨 ngx_http_request_t 中 所 有 成 员 的 意义 
(ngx_http_request_t 结 构 体 中 的 许多 成 员 只 有 HTTP 框 架 才 感 兴趣 ， 在 
11.3.1 节 会 更 详细 的 说 明 ) ， 只 介绍 一 下 获取 URI 和 参数 的 方法 ， 这 非 
常 简 单 ， 因 为 Nginx 提 供 了 多 种 方法 得 到 这 些 信息 。 下 面 先 介绍 相关 成 
员 的 定义 。 





typedef struct ngx_http_request_s ngx_http_request_t; 
struct ngx_http_request _s { 


ngx_uint_t method; 
ngx_uint_t http_version; 
ngx_str_t request_line,; 
ngx_str_t uri; 

ngx_str_t args; 
ngx_str_t exten; 
ngx_str_t unparsed_uri; 
ngx_str_t method_name; 
ngx_str_t http_protocol,; 
u_char *uri_start,; 
u_char *uri_end; 
u_char *uri_ext,; 
u_char *args_start; 
u_char *request_start; 
u_char *request_end; 
u_char *method_end; 
u_char *schema_start,; 
u_char *schema_end; 


在 对 一 个 用 户 请 求 行 进行 解析 时 ， 可 以 得 到 下 列 4 类 信息 。 
(1) 方法 名 


method 的 类 型 是 ngx_uint t《〈 无 符号 整 型 ) ， 它 是 Nginx 忽 略 大 小 写 


等 情形 时 解析 完 用 户 请 求 后 得 到 的 方法 类 型 ， 其 取 值 范围 如 下 所 示 。 





#define NGX_HTTP_UNKNOWN 0OXx0001 
#define NGX_HTTP_GET 0OX0002 
#define NGX_HTTP_HEAD OxO004 
#define NGX_HTTP_POST Ox0008 
#define NGX_HTTP_PUT Ox0010 
#define NGX_HTTP_DELETE Ox0020 
#define NGX_HTTP_MKCOL Ox0040 
#define NGX_HTTP_COPY Ox0080 
#define NGX_HTTP_MOVE Ox0100 
#define NGX_HTTP_OPTIONS Ox0200 
#define NGX_HTTP_PROPFIND Ox0400 
#define NGX_HTTP_PROPPATCH Ox0800 
#define NGX_HTTP_LOCK Ox1000 
#define NGX_HTTP_UNLOCK Ox2000 
#define NGX_HTTP_TRACE Ox4000 








当 需 要 了 解 用 户 请 求 中 的 HTTP 方 法 时 ， 应 该 使 用 r->method 这 个 整 
型 成 员 与 以 上 15 个 宏 进行 比 较 ， 这 样 速度 是 最 快 的 (如 果 使 用 
method_name 成 员 与 字符 串 做 比较 ， 那 么 效率 会 送 很 多 ) ， 大 部 分 情况 
下 推荐 使 用 这 种 方式 。 除 此 之 外 ， 还 可 以 用 method_name 取 得 用 户 请 求 
中 的 方法 名 字符 串 ， 或 者 联合 request_start 与 method_end 指 针 取 得 方法 
名 。method_name 是 ngx_str_t 类 型 ， 按 照 3.2.2 市 中 介绍 的 方法 使 用 即 


可 。 





request_start 与 method_end 的 用 法 也 很 简单 ， 其 中 request_start 指 同 用 
户 请 求 的 首 地 址 ， 同 时 也 是 方法 名 的 地 址 ，method_end 指 同方 法 名 的 最 








后 一 个 字符 〈 注 意 ， 这 点 与 其 他 xxx_end 指 针 不 同 ) 。 获 取 方 法 名 时 可 
以 从 request_start 开 始 回 后 过 历 ， 直 到 地 址 与 method_end 相 同 为 止 ， 这 上 段 
内 存 存储 着 方 法 名 。 





@@ 让。 Nginx 中 对 内 存 的 控制 相当 严格 ， 为 了 避免 不 必要 的 内 让 
开销 ， 许 多 需要 用 到 的 成 员 都 不 是 重新 分 配 内 存 后 存储 的 ， 而 是 直接 指 
向 用 户 请 求 中 的 相应 地 址 。 例 如 ，method_name.data、request_start 这 两 
个 指针 实际 指向 的 都 是 同一 个 地 址 。 而 且 ， 因 为 它们 是 简单 的 内 存 指 
针 ， 不 是 指向 字符 囊 的 指针 ， 所 以 ， 在 大 部 分 情况 下 ， 都 不 能 将 这 些 
u_charx 指 针 当 做 字符 串 使 用 。 


(2) URI 





ngx_str_t 类 型 的 uri 成 员 指 同 用 户 请 求 中 的 URI。 同 理 ，u_char* 类 型 
的 uri_start 和 uri_end 也 与 request_start、method_end 的 用 法 相似 ， 唯 一 不 
同 的 是 ，method_end 指 同方 法 名 的 最 后 一 个 字符 ， 而 uri_end 指 向 URI 结 
束 后 的 下 一 个 地 址 ， 也 就 是 最 后 一 个 字符 的 下 一 个 字符 地 址 (HTTP 框 
架 的 行为 )， 这 是 大 部 分 u_char* 类 型 指针 对 “xxx_start* 和 “xxx_end” 变 量 


的 用 法 。 











ngx_str_t 类 型 的 exten 成 员 指 加 用 户 请 求 的 文件 扩展 名 。 例 如 ， 在 访 
问 “GET/a.txt HTTP/1.1” 时 ，exten 的 值 是 {len=3,data="txt"}， 而 在 访 


问 “GET/a HTTP/1.1” 时 ，exten 的 值 为 空 ， 也 就 是 {len=0,data=0x0}。 


uri_ext 指 针 指 向 的 地 址 与 exten.data 相 同 。 





unparsed_uri 表 示 没 有 进行 URL 解 码 的 原始 请 求 。 例 如 ， 当 tri 为 “Va 
b” 时 ，unparsed_uri 是 “/a%20b”( 空 格 字 符 做 完 编码 后 是 %20) 。 


(3) URL 参 数 
args 指 向 用 户 请 求 中 的 URL 参 数 。 


args_start 指 向 URL 参 数 的 起 始 地 址 ， 配 合 uri_end 使 用 也 可 以 获得 
URL 参 数 。 


(4) 协议 版 本 





http_protocol 的 data 成 员 指 同 用 户 请 求 中 HTTP 协 议 版 本 字符 串 的 起 
始 地 址 ，len 成 员 为 协议 版 本 字符 串 长 度 。 


http_version 是 Nginx 解 析 过 的 协议 版 本 ， 它 的 取 值 范围 如 下 : 





#define NGX_HTTP_VERSION_9 9 
#define NGX_HTTP_VERSION_10 1000 
#define NGX_HTTP_VERSION_11 1001 





建议 使 用 http_version 分 析 HTTP 的 协议 版 本 。 


最 后 ， 使 用 request_start 和 request_end 可 以 获取 原始 的 用 户 请 求 行 。 


3.6.3 ”获取 HTTP 头 部 


在 ngx_http_request_t*r 中 就 可 以 取 到 请 求 中 的 HTTP 头 部 ， 比 如 使 用 
下 面 的 成 员 : 











struct ngx_http_request_s { 


ngx_buf_t *header_in; 
ngx_http_headers_in tt headers_in; 


}; 





其 中 ，header_in 指 辣 Nginx 收 到 的 未 经 解析 的 HTTP 头 部 ， 这 里 暂 不 
关注 它 〈 在 第 11 章 中 可 以 看 到 ，header_ in 就 是 接收 HTTP 头 部 的 缓冲 
区 ) 。ngx_http_headers_in_t 类 型 的 headers_in 则 存储 已 经 解析 过 的 HTTP 
头 部 。 下 面 介 绍 ngx_http_headers_in_t 结 构 体 中 的 成 员 。 








typedef struct { 
/* 所 有 解析 过 的 


HTTP 头 部 都 在 


headers 链 表 中 ， 可 以 使 用 


3.2.3 节 中 介绍 的 遍历 链表 的 方法 来 获取 所 有 的 


HTTP 头 部 。 注 意 ， 这 里 


headers 链 表 的 每 一 个 元 素 都 是 


ngx_table_elt_t 成 员 


*/ 
ngx_list_t 
/A* 以 干 每 个 


ngx_table_elt_t 成 员 都 是 


RFC2616 规 范 中 定义 的 


HTTP 头 部 ， 


它们 实际 都 指向 


headers 链 表 中 的 相应 成 员 。 注 意 ， 当 它们 为 


NULL 空 指针 时 ， 表 示 没有 解析 到 相应 的 


HTTP 头 部 


*/ 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 

#if (NGX_HTTP_GZIP) 
ngx_table elt_t 
ngx_table elt_t 

#endif 
ngx_table elt_t 
ngx_table elt_t 


headers; 


*host; 

*connection,; 
*if_modified_since,; 
*if_unmodified_since; 
*USer_agent 
*referer,; 
*content_length,; 
*content_type; 
*range; 

*if_range; 
*transfer_encoding; 
*expect,; 


*accept_encoding; 
*Vvia; 


*authorization; 
*keep_alive; 


#if (NGX_HTTP_PROXY || NGX_HTTP_REALIP || NGX_HTTP_GEO) 


ngx_table elt_t 
#endif 
#if (NGX_HTTP_REALIP) 
ngx_table elt_t 
#endif 


#if (NGX_HTTP_HEADERS) 


ngx_table elt_t 
ngx_table elt_t 
#endif 


*x_forwarded_for; 


*x_real_ip; 


*accept,; 
*accept_language; 


#if (NGX_HTTP_DAV) 


ngx_table elt_t *depth; 
ngx_table elt_t *destination; 
ngx_table elt_t *overwrite; 
ngx_table elt_t *date; 

#endif 
/*USer 和 和 

passwd 是 只 有 





ngx_http_auth_basic_module 才 会 用 到 的 成 员 ， 这 里 可 以 忽略 


*/ 
ngx_str_t user,; 
ngx_str_t passwd; 
/*cOOKkies 是 以 


ngx_array_t 数 组 存储 的 ， 本 章 先 不 介绍 这 个 数据 结构 ， 感 兴趣 的 话 可 以 直接 跳 到 


ngx_array 七 的 相关 用 法 


*/ 
ngx_array_t cookies; 
// server 名 称 


ngx_str_t server; 
// 根据 


ngx_table_elt_t *content_length 计 算出 的 


HTTP 包 体 大 小 


off_t content_length_n; 
time_t keep_alive_n; 
A/*HTTP 连 接 类 型 ， 它 的 取 值 范围 是 


0、 


NGX_http_CONNECTION_CLOSE 或 者 


NGX_HTTP_CONNECTION_KEEP_ALIVE*/ 
unsigned connection_type:2; 
/x* 以 下 


7 个 标志 位 是 


HTTP 框 架 根据 浏览 器 传 来 的 “ 


Useragent” 头 部 ， 它 们 可 用 来 判断 浏览 器 的 类 型 ， 值 为 


1 时 表示 是 相应 的 浏览 器 发 来 的 请 求 ， 值 为 


9 时 则 相反 

*/ 
unsigned msie:1; 
unsigned msie6:1; 
unsigned opera:1,; 
unsigned gecko:1; 
unsigned chrome:1; 
unsigned safari:1; 
unsigned konqueror:1; 


} ngx_http_headers _ in _t; 





获取 HTTP 头 部 时 ， 直 接 使 用 r->headers_ in 的 相应 成 员 就 可 以 了 。 这 
里 举例 说 明 一 下 如 何 通过 遍历 headers 链 表 获 取 非 RFC2616 标 准 的 HTTP 
头 部 ， 读 者 可 以 先 回顾 一 下 ngx_list_t 链 表 和 ngx_table_elt_t 结 构 体 的 用 
法 。 前 面 3.2.3 节 中 已 经 介绍 过 ，headers 是 一 个 ngx_list_t 链 表 ， 它 存储 着 
解析 过 的 所 有 HTTP 头 部 ， 链 表 中 的 元 素 都 是 ngx_table_elt t 类 型 。 下 面 
尝试 在 一 个 用 户 请 求 中 找到 “Rpc-Description” 头 部 ， 首 先 判 断 其 值 是 否 
为 “uploadFile”， 再 决定 后 续 的 服务 器 行为 ， 代 码 如 下 。 








ngx_list_part_t *part = &r->headers_in.headers.part; 
ngx_table elt t *header = part->elts,; 
// 开始 遍历 链表 


for (i = 0; /* void */; I++) { 
// 判断 是 否 到 达 链 表 中 当前 数组 的 结尾 处 


if (i >= part->nelts) { 
// 是 否 还 有 下 一 个 链表 数组 元 素 


if (part->next == NULL) { 
break; 
} 
/* part 设 置 为 
next 来 访问 下 一 个 链表 数组 ; 
header 也 指向 下 一 个 链表 数组 的 首 地 址 ; 
i 设置 为 


09 时， 表示 从 头 开始 遍历 新 的 链表 数组 


*/ 
part = part->next,; 
header = part->elts; 
i= 0; 
} 
// hash 为 
旧时 表示 不 是 合法 的 头 部 


If (header[il].hash == 0) { 
continue; 
} 7 ~ [i 
/* 判 断 当 前 的 头 部 是 否 是 
Rpc-Description”。 如 果 想 要 忽略 大 小 写 ， 则 应 该 先 用 


header[i] ,Lowcase_key 人 代替 


header[i].key.data， 然 后 比较 字符 串 


xs 
if (0 == ngx_strncasecmp(header[i].Kkey.data, 
(u_char*) "Rpc-Description", 
header[i].key.1en)) 
{ 


// 判断 这 个 


« 


HTTP 头 部 的 值 是 否 是 


uploadFile” 


if (90 == ngx_strncmp(header[i].value.data, 
"uploadFile", 
header[i].value.1en)) 


// 找到 了 正确 的 头 部 ， 继 续 向 下 执行 








对 于 常见 的 HTTP 头 部 ， 直 接 获 取 r->headers_ in 中 已 经 由 HTTP 框 架 
解析 过 的 成 员 即 可 ， 而 对 于 不 常见 的 HTTP 头 部 ， 需 要 遍历 r- 


>headers_in.headers 链 表 才 能 获得 。 





3.6.4 获取 HTTP 包 体 


HTTP 包 体 的 长 度 有 可 能 非常 大 ， 如 果 试 图 一 次 性 调用 并 读 取 完 所 
有 的 包 体 ， 那 么 多 半 会 阻塞 Nginx 进 程 。HTTP 框 架 提供 了 一 种 方法 来 异 
步 地 接收 包 体 : 





ngx_int_t ngx_http_read client request body(ngx_http_request _t *r, ngx_http_client 上 








ngx_http_read_client_request_body 是 一 个 异步 方法 ， 调 用 它 只 是 说 
明 要 求 Nginx 开 始 接收 请 求 的 包 体 ， 并 不 表示 是 否 已 经 接收 完 ， 当 接收 
完 所 有 的 包 体内 容 后 ，post_handler 指 向 的 回调 方法 会 被 调用 。 因 此 ， 即 
使 在 调用 了 ngx_http_read_client_request_body 方 法 后 它 已 经 返回 ， 也 无 








法 确定 这 时 是 否 已 经 调用 过 post_handler 指 向 的 方法 。 换 名 话说 ， 
ngx_http_read_client_request_body 返 回 时 既 有 可 能 已 经 接收 完 请 求 中 所 
有 的 包 体 (假如 包 体 的 长 度 很 小 ) ， 也 有 可 能 还 没 开始 接收 包 体 。 如 果 
ngx_http_read_client_request_body 是 在 ngx_http_mytest_handler 处 理 方法 
中 调用 的 ， 那 么 后 者 一 般 要 返回 NGX_DONE， 因 为 下 一 步 就 是 将 它 的 
返回 值 作为 参数 传 给 ngx_http_finalize_request。NGX_ DONE 的 意义 在 


3.6.1 节 中 己 经 介绍 过 ， 这 里 不 再 歼 述 。 








下 面 看 一 下 包 体 接收 完毕 后 的 回调 方法 原型 
ngx_http_client_body_handler_pt 是 如 何 定 义 的 : 





typedef void (*ngx_http_client body_handler_pt)(ngx_http_request t *r); 








其 中 ， 有 参数 ngx_http_request_t*r， 这 个 请 求 的 信息 都 可 以 从 r 中 获 
得 。 这 样 可 以 定义 一 个 方法 void func(ngx_http_request_t*r)， 在 Nginx 接 
收 完 包 体 时 调用 它 ， 男 外 ， 后 续 的 流程 也 都 会 写 在 这 个 方法 中 ， 例 如 : 











void ngx_http_mytest_body_handler(ngx_http_request_t *r) 
{ 





@ 注意 ”ngx_http_mytest_body_handlet 的 返回 类 型 是 void，Noinx 
不 会 根据 返回 值 做 一 些 收尾 工作 ， 因 此 ， 我 们 在 该 方法 里 处 理 完 请 求 时 


必须 要 主动 调用 ngx_http_finalize_request 方 法 来 结束 请 求 。 


接收 包 体 时 可 以 这 样 写 : 





ngx_int_t rc = ngx_http_read_client_reduest_body(r，ngx_http_mytest_body_har 
if (rc >= NGX_HTTP_SPECIAL RESPONSE) { 
return rc; 








} 
return NGX_DONE; 








Nginx 异 步 接 收 HTTP 请 求 的 包 体 的 内 容 将 在 11.8 节 中 详 述 。 


如 果 不 想 处 理 请 求 中 的 包 体 ， 那 么 可 以 调用 
ngx_http_discard_request_body 方 法 将 接收 自 客 户 端 的 HTTP 包 体 丢 弃 
掉 。 例 如 : 





ngx_jint _t rc = ngx_http_discard request_ body(r); 
if (rc != NGX_0OK) { 
return rc; 


} 





ngx_http_discard_request_body 只 是 丢弃 包 体 ， 不 处 理 包 体 不 就 行 了 
吗 ? 何必 还 要 调用 ngx_http_discard_request_body 方 法 呢 ?” 其 实 这 一 步 非 
常 有 意义 ， 因 为 有 些 客户 端 可 能 会 一 直 试 图 发 送 包 体 ， 而 如 果 HTTP 模 
块 不 接收 发 来 的 TCP 流 ， 有 可 能 造成 客户 端 发 送 超时 。 





接收 完 请 求 的 包 体 后 ， 可 以 在 r->request_body->temp_file->file 中 获 
取 临 时 文件 (假定 将 r->request_body_in_file_only 标 志 位 设 为 1， 那 就 一 
定 可 以 在 这 个 变量 获取 到 包 体 。 更 复杂 的 接收 包 体 的 方式 本 节 和 暂 不 讨 





论 ) 。fie 是 一 个 ngx_file t 类 型 ， 在 3.8 节 会 详细 介绍 它 的 用 法 。 这 里 ， 
我 们 可 以 从 r->request_body->temp_file->file.name 中 获取 Nginx 接 收 到 的 
请 求 包 体 所 在 文件 的 名 称 〈 包 括 路 径 ) 。 


3.7 发送 啊 应 


请 求 处 理 完毕 后 ， 需 要 向 用 户 发 送 HTTP 响 应 ， 告 知客 户 端 Nginx 的 
执行 结果 。HITP 啊 应 主要 包括 响应 行 、 啊 应 头 部 、 包 体 三 部 分 。 发 送 
HTTP 响应 时 需要 执行 发 送 HITTP 头 部 《发送 HITP 头 部 时 也 会 发 送 啊 应 
行 ) 和 发 送 HTTP 包 体 两 步 操作 。 本 节 将 以 发 送 经 典 的 “Hello World” 为 
例 来 说 明 如 何 发 送 响 应 。 








3.7.1 发 送 HTTP 头 部 


下 面 看 一 下 HTTP 框 架 提供 的 发 送 HTTP 头 部 的 方法 ， 如 下 所 示 。 





ngx_int_t ngx_http_send_header(ngx_http_request t *r); 








调用 ngx_http_send_header 时 把 ngx_http_request_t 对 象 传 给 它 即 可 ， 
而 ngx_http_send_header 的 返回 值 是 多 样 的 ， 在 本 节 中 ， 可 以 认为 返回 
NGX_ERROR 或 返回 值 大 于 0 就 表示 不 正常 ， 例 如 : 








ngx_int t rc = ngx_http_send_header(r); 

if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) { 
return rc; 

} 





下 面 介 绍 设置 啊 应 中 的 HITP 头 部 的 过 程 。 


如 同 headers_in，ngx_http_request_t 也 有 一 个 headers_out 成 员 ， 用 来 
设置 响应 中 的 HITP 头 部 ， 如 下 所 示 。 





struct ngx_http_request_s { 


ngx_http_headers_in t headers_in; 
ngx_http_headers out_t headers_out ; 


}; 





只 要 指定 headers_out 中 的 成 员 ， 束 可 以 在 调用 ngx_http_send_header 
时 正确 地 把 HTTP 头 部 发 出 。 下 面 介绍 headers_out 的 结构 类 型 


ngx_http_headers_out t。 





typedef struct { 
// 待 发 送 的 


HTTP 头 部 链表 ， 与 


headers_in 中 的 


headers 成 员 类 似 


ngx_list_t headers; 
/* 响 应 中 的 状态 值 ， 如 


200 表 示 成 功 。 这 里 可 以 使 用 


NGX_HTTP_OK */ 
ngx_uint_t status; 
// 响应 的 状态 行 ， 如 “ 


HTTP/1.1 201 CREATED” 


ngx_Sstr 七 
/* 以 下 成 员 (包括 


ngx_table_elt_t) 都 是 


RFC1616 规 范 中 定义 的 


HTTP 头 部 ， 设 置 后 ， 


ngx_http_header_filter_module 过 滤 模 块 可 以 把 它们 加 到 待 发 送 的 网 络 包 中 





*/ 

ngx_table elt_t 
ngx_table elt_t 
ngx_table elt _t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_str_t 

/* 可 以 调用 


status_line; 


*server; 

*date; 
*content_length,; 
*content_encoding; 
*location; 
*refresh,; 
*last_modified; 
*content_range; 
*accept_ranges; 
*www_authenticate; 
*expires; 

*etag; 
*override_charset,; 


ngx_http_set_content_type(r) 方 法 帮助 我 们 设置 


Content-Type 头 部 ， 这 个 方法 会 根据 


URI 中 的 文件 扩展 名 并 对 应 着 


mime ,type 来 设置 


Content -Type 值 


*/ 
size 七 
ngx_str_t 
ngx_str_t 
u_char 
ngx_uint_t 
ngx_array_t 


content_type_len; 
content_type; 
Charset 


*content_type_lowcase; 


content_type_hash ; 
cache_control,; 


/* 在 这 里 指定 过 


content_length_n 后 ， 不 用 再 次 到 


ngx_table_elt_t *content_ length 中 设置 响应 长 度 


*/ 
off_t content_length_n; 
time_t date_time; 
time_t last_modified_time,; 


} ngx_http_headers out_t; 





在 向 headers 链 表 中 添加 自 定义 的 HTTP 头 部 时 ， 可 以 参考 3.2.3 节 中 
ngx_list_push 的 使 用 方法 。 这 里 有 一 个 简单 的 例子 ， 如 下 所 示 。 





ngx_table elt_t* h = ngx_list_push(&r->headers_out.headers); 
if (h == NULL) { 
return NGX_ERROR ， 


->hash = 1; 

->key.len = sizeof("TestHead") - 1; 
->key.data = (u_char *) "TestHead",; 
->value.len = sizeof("TestValue") - 1; 
->value.data = (u_char *) "TestValue"; 


可 本 了 本本 一 





这 样 将 会 在 啊 应 中 新 增 一 行 HITP 头 部 : 





TestHead: TestValue\r\n 








如 果 发 送 的 是 一 个 不 含有 HTTP 包 体 的 啊 应 ， 这 时 就 可 以 直接 结束 
请 求 了 例如， 在 ngx_http_mytest_handler 方 法 中 ， 直 接 在 
ngx_http_send_header 方 法 执行 后 将 其 返回 值 return 即 可 ) 。 


@ ; 注意 nex_http_sendq_headet 方 法 会 首先 调用 所 有 的 HTTP 过 滤 模 
块 共同 处 理 headers_out 中 定义 的 HTTP 响 应 头 部 ， 全 部 处 理 完毕 后 才 会 


序列 化 为 TCP 字 符 流 发 送 到 客户 端 ， 相 关 流 程 可 参见 11.9.1 节 。 


3.7.2 ”将 内 存 中 的 字符 串 作 为 包 体 发 送 





调用 ngx_http_output_filter 方 法 即 可 回 客 户 端 发 送 HTTP 啊 应 包 体 ， 
下 面 查 看 一 下 此 方法 的 原型 ， 如 下 所 示 。 





ngx_int_t ngx_http_output_filter(ngx_http_request_t *r, ngx_chain_t *in); 








ngx_http_output_filter 的 返回 值 在 mytest 例 子 中 不 需要 处 理 ， 通 过 在 
ngx_http_mytest_handler 方 法 中 返回 的 方式 传递 给 
ngx_http_finalize_request 即 可 。ngx_chain_t 结 构 已 经 在 3.2.6 节 中 介绍 
过 ， 它 仅 用 于 容纳 ngx_buf t 绥 冲 区 ， 所 以 需要 先 了 解 一 下 如 何 使 用 
ngx_buf_t 分 配 内 存 。 下 面 介 绍 Nginx 的 内 存 池 是 如 何 分 配 内 存 的 。 








为 了 减少 内 存 碎片 的 数量 ， 并 通过 统一 管理 来 减少 代码 中 出 现 内 存 
泄漏 的 可 能 性 ，Nginx 设 计 了 ngx_pool t 内 存 池 数据 结构 。 本 章 我 们 不 会 
深入 分 析 内 存 池 的 实现 ， 只 关注 内 存 池 的 用 法 。 在 
ngx_http_mytest_handler 处 理 方法 传 来 的 ngx_http_request_t 对 象 中 就 有 这 
个 请 求 的 内 存 池 管理 对 象 ， 我 们 对 内 存 池 的 操作 都 可 以 基于 它 来 进行 ， 
这 样 ， 在 这 个 请 求 结束 的 时 候 ， 内 存 池 分 配 的 内 存 也 都 会 被 释放 。 














struct ngx_http_request _s { 


ngx_pool_t *pool; 








实际 上 ， 在 r 中 可 以 获得 许多 内 存 池 对 象 ， 这 些 内 存 池 的 大 小 、 意 
义 及 生存 期 各 不 相同 。 第 3 部 分 会 涉及 许多 内 存 池 ， 本 章 使 用 r->pool 内 
存 池 即 可 。 有 了 ngx_pool {对象 后 ， 可 以 从 内 存 池 中 分 配 内 存 。 例 如 ， 
下 面 这 个 基本 的 申请 分 配 内 存 的 方法 : 








void *ngx_palloc(ngx_pool t *pool, size t size); 





其 中 ，ngx_palloc 函 数 将 会 从 pool 内 存 池 中 分 配 到 size 字 节 的 内 存 ， 
并 返回 这 段 内 存 的 起 始 地 址 。 如 果 返 回 NULL 空 指针 ， 则 表示 分 配 失 
败 。 还 有 一 个 封装 了 ngx_palloc 的 函数 ngx_pcalloc， 它 多 做 了 一 件 事 ， 
就 是 把 ngx_palloc 申 请 到 的 内 存 块 全 部 置 为 0， 虽 然 ， 多 数 情况 下 更 适合 
用 ngx_pcalloc 来 分 配 内 存 。 


假如 要 分 配 一 个 ngx_buf t 结 构 ， 可 以 这 样 做 : 





ngx_buf_t* b = ngx_pcalloc(r->pool, sizeof(ngx_buf_t)); 








这 样 ，ngx_buf_t 中 的 成 员 指 辣 的 内 存 仍然 可 以 继续 分 配 ， 例 如 : 





b->start = (u_char*)ngx_pcalloc(r->pool, 128); 
b->pos = b->start,; 

b->last = b->start; 

b->end = b->last + 128; 


b->temporary = 1; 





实际 上 ，Nginx 还 封装 了 一 个 生成 ngx_buf t 的 简便 方法 ， 它 完全 等 
价 于 上 面 的 6 行 语 多， 如 下 所 示 。 








ngx_buf t *b = ngx_create temp_buf(r->pool, 128); 





分 配 完 内 存 后 ， 可 以 同 这 段 内 存 写 入 数据 。 当 写 完 数 据 后 ， 要 让 b- 
>last 指 针 指 回 数据 的 末尾 ， 如 果 b->last 与 b->pos 相 等 ， 那 么 HTTP 框 架 是 
不 会 发 送 一 个 字 贡 的 包 体 的 。 





最 后 ， 把 上 面 的 ngx_buf_t*b 用 ngx_chain_t 传 给 ngx_http_output_filter 
方法 就 可 以 发 送 HTTP 响 应 的 包 体内 容 了 。 例 如 : 





ngx_chain_t out; 

out.buf = b; 

out.next = NULL; 

return ngx_http_output_filter(r, &out); 





了 注意 ”在 向 用 户 发 送 响应 包 体 时 ， 必 须 牢 记 Nginx 是 全 异步 的 服 
务 器 ， 也 就 是 说 ， 不 可 以 在 进程 的 栈 里 分 配 内 存 并 将 其 作为 包 体 发 送 。 
当 一 直 ngx_http_output_filter 方 法 返回 时 ， 可 能 由 于 TCP 连 接 上 的 缓冲 区 
还 不 可 写 ， 所 以 导致 ngx_buf t 缓 冲 区 指向 的 内 存 还 没有 发 送 ， 可 这 时 方 
法 返回 已 把 控制 权 交 给 Nginx 了 ， 又 会 导致 栈 里 的 内 存 被 释放 ， 最 后 就 
造成 内 存 越界 错误 。 因 此 ， 在 发 送 响 应 包 体 时 ， 尽 量 将 ngx_buf t 中 的 
pos 指 针 指 向 从 内 存 池 里 分 配 的 内 存 。 


3.7.3 ”经典 的 “Hello World” 示 例 








下 面 以 经 典 的 返回 “Hello World” 为 例 来 编写 一 个 最 小 的 HTTP 人 处 理 
模块 ， 以 此 介绍 完整 的 ngx_http_mytest_handler 处 理 方法 。 





static ngx_int_t ngx_http_mytest_handler(ngx_http_request t *r) 





// 必须 是 
GET 或 者 
HEAD 方 法 ， 和 否则 返回 


405 Not Allowed 
if (!(r->method & (NGX_HTTP_GET|NGX_HTTP_HEAD))) { 
return NGX_HTTP_NOT_ALLOWED ; 


} 
// 丢弃 请 求 中 的 包 体 


ngx_int_t rc = ngx_http_discard_request_body(r); 
if (rc != NGX_OK) { 
return rc; 
} 
/* 设 置 返回 的 
Content -Type。 注 意 ， 
ngx_str_t 有 一 个 很 方便 的 初始 化 宏 
ngx_string， 它 可 以 把 
ngx_str_t 的 
data 和 


en 成 员 都 设置 好 


*/ 
ngx_str_t type = ngx_string("text/plain"); 
// 返回 的 包 体 内 容 


ngx_str_t response = ngx_string("Hello World!"); 
// 设置 返回 状态 码 


r->headers_out.status = NGX_HTTP_OK; 
// 响应 包 是 有 包 体 内 容 的 ， 需 要 设置 


Content -Length 长 度 
r->headers_out.content_length_n = response,.1len; 
// 设置 


Content-Type 
r->headers_out.content_type = type; 
// 发 送 


HTTP 头 部 
rc = ngx_http_send_header(r); 


if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) { 
return rc; 


} 
// 构造 


ngx_buf_t 结 构 体 准备 发 送 包 体 


ngx_buf_t *b; 
b = ngx_create temp_buf(r->pool, response.1en); 
if (b == NULL) { 
return NGX_HTTP_INTERNAL_SERVER_ERROR; 
} 


// 将 


Hello World 复 制 到 


ngx_buf_t 指 向 的 内 存 中 


ngx_memcpy(b->pos, response.data, response.1en); 
// 注意 ， 一定 要 设置 好 


]ast 指 针 


b->last = b->pos + response.1len; 
// 声明 这 是 最 后 一 块 缓冲 区 


b->last_buf = 1; 
// 构造 发 送 时 的 


ngx_chain tt 结构 体 


ngx_chain_t out 
// 赋值 


ngx_buf_t 
out.buf = b; 
// 设置 


next 为 


NULL 
out.next = NULL; 
/* 最 后 一 步 为 发 送 包 体 ， 发 送 结束 后 


HTTP 框 架 会 调用 
ngx_http_finalize_request 方 法 结束 请 求 


4 
return ngx_http_output_filter(r, &out); 
} 





3.8 将 破 盘 文件 作为 包 体 发 送 


上 文 讨 论 了 如 何 将 内 存 中 的 数据 作为 包 体 发 送 给 客户 闫 ， 而 在 发 送 
文件 时 完全 可 以 先 把 文件 读 取 到 内 存 中 再 癌 用 户 发 送 数 据 ， 但 是 这 样 做 
会 有 两 个 缺点 : 





` 为 了 不 阻塞 Nginx， 每 次 只 能 读 取 并 发 送 磁盘 中 的 少量 数据 ， 需 
要 反复 持续 多 次 。 

Linux 上 高 效 的 sendfile 系 统 调用 不 需要 先 把 磁盘 中 的 数据 读 取 到 
用 户 态 内 存 再 发 送 到 网 络 中 。 





当然 ，Nginx 已 经 封闭 好 了 多 种 接口 ， 以 便 将 磁盘 或 者 缓存 中 的 文 
件 发 送 给 用 户 。 





3.8.1 如 何 发 送 磁盘 中 的 文件 


发 送 文 件 时 使 用 的 是 3.7 市 中 所 介绍 的 接口 。 例 如 : 





ngx_chain_t out; 

out.buf = b; 

out .next = NULL; 

return ngx_http_output_filter(r, &out); 





两 者 不 同 的 地 方 在 于 如 何 设置 ngx_buf t 绥 冲 区 。 在 3.2.5 节 中 介绍 


过 ，ngx_buf t 有 一 个 标志 位 in_file， 将 in_file 置 为 1 就 表示 这 次 ngx_buf { 
缓冲 区 发 送 的 是 文件 而 不 是 内 存 。 调 用 ngx_http_output_filter 后 ， 若 
Nginx 检 测 到 in_file 为 1， 将 会 从 ngx_buf t 绥 冲 区 中 的 file 成 员 处 获取 实际 
的 文件 。file 的 类 型 是 ngx_file t+， 下 面 看 一 下 ngx_file_t 的 结构 。 





typedef struct ngx_file s ngx_file t; 
struct ngx_file s { 
// 文件 句柄 描述 符 





ngx_fd t fd; 
// 文件 名 称 


ngx_str_t name; 
// 文件 大 小 等 资源 信息 ， 实 际 就 是 


Linux 系 统 定义 的 


Stat 结 构 


ngx_file_info_t info; 
/* 该 偏 移 量 告诉 


Nginx 现 在 处 理 到 文件 何 处 了 ， 一 般 不 用 设置 它 ， 


Nginx 框 架 会 根据 当前 发 送 状态 设置 它 


*/ 
off_t offset; 
// 当前 文件 系统 偏 移 量 ， 一 般 不 用 设置 它 ， 同 样 由 


Nginx 框 架设 置 


off_t sys_offset,; 
// 日 志 对 象 ， 相 关 的 日 志 会 输出 到 


10g 指 定 的 日 志文 件 中 


ngx_log_t *1og 
// 目前 未 使 用 


unsigned valid info:1; 


// 与 配置 文件 中 的 


directio 配 置 项 相对 应 ， 在 发 送 大 文件 时 可 以 设 为 


unsigned directio:1; 





fd 是 打开 文件 的 句柄 描述 符 ， 打 开 文 件 这 一 步 需要 用 户 上 自己 来 做 。 
Nginx 简 单 封装 了 一 个 宏 用 来 代 蔡 open 系 统 的 调用 ， 如 下 所 示 。 





#define ngx_open file(name, mode, create, access) \ 
open((const char *) name, model|create, access) 





实际 上 ，ngx_open_file 与 open 方 法 的 区 别 不 大 ，ngx_open_file 返 回 
的 是 Linux 系 统 的 文件 句柄 。 对 于 打开 文件 的 标志 位 ，Nginx 也 定义 了 以 
下 几 个 宏 来 加 以 封装 。 





#define NGX_FILE_RDONLY 0_RDONLY 

#define NGX_FILE WRONLY 0_WRONLY 

#define NGX_FILE_ RDWR O_RDWR 

#define NGX_FILE CREATE_ OR_OPEN O_CREAT 
#define NGX_FILE OPEN 0 

#define NGX_FILE TRUNCATE 0O_CREAT|O_TRUNC 
#define NGX_FILE APPEND 0_WRONLY|0_APPEND 
#define NGX_FILE NONBLOCK 0_NONBLOCK 
#define NGX_FILE DEFAULT_ACCESS 0644 
#define NGX_FILE OWNER ACCESS 0600 








因此 ， 在 打开 文件 时 只 需要 把 文件 路 径 传 递 给 name 参 数 ， 并 把 打开 


方式 传递 给 mode、create、access 参 数 即 可 。 例 如 : 





ngx_buf_t *b， 

b = ngx_palloc(r->pool, sizeof(ngx_buf_t)); 

u_char* filename = (u_char*)"/tmp/test.txt",; 

>in_file = 1; 

b->file = ngx_pcalloc(r->pool, sizeof(ngx_file t)); 

b->file->fd = ngx_open_file(filename, NGX_FILE_ RDONLY|NGX_FILE NONBLOCK, NGX_FILE_OF 
b->file->1og = r->connection->1log; 
b 
b 
i 


So 
1 


->file->name.data = filename; 
->file->name.len = Strlen(filename ) ， 
if (b->file->fd <= 0) 
{ 


return NGX_HTTP_NOT_FOUND ， 








到 这 里 其 实 还 没有 结束 ， 还 需要 告知 Nginx 文 件 的 大 小 ， 包 括 设置 
啊 应 中 的 Content-L a 部 ， 以 及 设置 ngx_buf_t 缓 冲 区 的 file_pos 和 
file_last。 实 际 上 ， 通 过 ngx_file_t 结 构 里 ngx_file_info_t 类 型 的 info 变 量 就 
可 以 获取 文件 信息 : 





typedef struct stat ngx_file_info tt， 





Nginx 不 只 对 stat 数 据 结构 做 了 封装 ， 对 于 由 操作 系统 中 获取 文件 信 
恩 的 stat 方 法 ，Nginx 也 使 用 一 个 宏 进行 了 简单 的 封装 ， 如 下 所 示 : 





#define ngx_file info(file, sb) stat((const char *) file, sb) 





因此 ， 获 取 文 件 信 息 时 可 以 先 这 样 写 : 





if (ngx_file info(filename, &b->file->info) == NGX_FILE_ ERROR) { 
return NGX_HTTP_INTERNAL_SERVER_ERROR ， 
} 





之 后 必须 要 设置 Content-Length 头 部 : 





r->headers_out.content_Jength_n = b->file->info.st_ size; 





还 需要 设置 ngx_buf {t 绥 冲 区 的 fle pos 和 file_last: 





b->file_pos = 0; 
b->file last = b->file->info.st_size; 





这 里 是 告诉 Nginx 从 文件 的 身 e_pos 偏 移 量 开始 发 送 文 件 ， 一 直到 达 
file_last 偏 移 量 处 截止 。 


@@ 注意 当 破 盘 中 有 大 量 的 小 文件 时 ， 会 占用 Linux 文 件 系统 中 过 
多 的 inode 结 构 ， 这 时 ， 成 熟 的 解决 方案 会 把 许多 小 文件 合并 成 一 个 大 文 
件 。 在 这 种 情况 下 ， 当 有 需要 时 ， 只 要 把 上 面 的 fle_ pos 和 fle_ last 设 置 为 
合适 的 偏 移 量 ， 就 可 以 只 发 送 合并 大 文件 中 的 某 一 块 内 容 〈 原 来 的 小 文 
件 ) ， 这 样 就 可 以 大 幅 降 低 小 文件 数量 。 


3.8.2 ”清理 文件 句柄 


Nginx 会 异步 地 将 整个 文件 高 效 地 发 送 给 用 户 ， 但 是 我 们 必须 要 求 
HTTP 框 架 在 响应 发 送 完 毕 后 关闭 已 经 打开 的 文件 句柄 ， 否 则 将 会 出 现 
句柄 泄露 问题 。 设 置 清 理 文 件 句柄 也 很 简单 ， 只 需要 定义 一 个 
ngx_pool_cleanup_t 结 构 体 〈 这 是 最 简单 的 方法 ，HTTP 框 架 还 提供 了 其 


他 方式 ， 在 请 求 结束 时 回调 各 个 HITTP 模 块 的 cleanup 方 法 ， 将 在 第 11 章 
介绍 ) ， 将 我 们 刚 得 到 的 文件 句柄 等 信息 赋 给 它 ， 并 将 Nginx 提 供 的 

ngx_pool_cleanup_file 函 数 设置 到 它 的 handler 回 调 方法 中 即 可 。 首 先 介 
绍 一 下 ngx_pool_cleanup_t 结 构 体 。 





typedef struct ngx_ pool cleanup_s ngx_pool cleanup_t; 
struct ngx_pool cleanup_s { 
// 执行 实际 清理 资源 工作 的 回调 方法 


ngx_pool cleanup_pt handler; 
// handler 回 调 方法 需要 的 参数 


void *data; 
// 下 一 个 


ngx_pool_cleanup_t 清 理 对 象 ， 如 果 没 有 ， 需 置 为 


NULL 
ngx_pool_cleanup_t *next,; 


了 











设置 好 handler 和 data 成 员 就 有 可 能 要 求 HTTP 框 架 在 请 求 结束 前 传 入 
data 成 员 回调 handler 方 法 。 接 着 ， 介 绍 一 下 专用 于 关闭 文件 句柄 的 
ngx_pool_cleanup_file 方 法 。 





void ngx_pool cleanup_file(void *data) 


ngx_pool cleanup_file t *c = data; 
ngx_log_debug1i(NGX_LOG_ DEBUG ALLOC, c->lo0g, 0, "file cleanup: fd:%d",c->fd); 
If (ngx_close file(c->fd) == NGX_FILE_ ERROR) { 
ngx_1log_error(NGX LOG ALERT, c->lo0g, ngx_errno, 
ngx_close_ file n " \"%s\" failed", c->name); 


ngx_pool_cleanup_file 的 作用 是 把 文件 句柄 关闭 。 从 上 面 的 实现 中 
可 以 看 出 ，ngx_pool_cleanup_file 方 法 需要 一 个 ngx_pool_cleanup_file tf 
类 型 的 参数 ， 那 么 ， 如 何 提供 这 个 参数 呢 ? 在 ngx_pool_cleanup_t 结 构 体 


的 data 成 员 上 赋值 即 可 。 下 面 介绍 一 下 ngx_pool_cleanup_file_t 的 结构 。 





typedef struct { 
// 文件 句柄 


ngx_fd t fd; 
// 文件 名 称 


u_char *name 
// 日 志 对 象 


ngx_log_t *1og ， 
} ngx_pool cleanup_file_t; 





可 以 看 到 ，ngx_pool_cleanup_file_t 中 的 对 象 在 ngx_buf t 组 冲 区 的 
file 结 构 体 中 都 出 现 过 了 ， 意 义 也 是 相同 的 。 对 于 他 e 结 构 体 ， 我 们 在 内 
存 池 中 已 经 为 它 分 配 过 内 存 ， 只 有 在 请 求 结束 时 才 会 释放 ， 因 此 ， 这 里 
简单 地 引用 fe 里 的 成 员 即 可 。 清 理 文件 句柄 的 完整 代码 如 下 。 





ngx_pool cleanup_t* cln = ngx_pool cleanup_ add(r->pool, sizeof(ngx_pool cleanup_filt 
if (cln == NULL) { 
return NGX_ERROR,; 


cln->handler = ngx_pool cleanup_file; 
ngx_pool cleanup_file t *clnf = cln->data; 
clnf->fd = b->file->fd; 

clnf->name = b->file->name.data; 

clnf->]log = r->pool->lo0g; 


ee | 


ngx_pool_cleanup_add 用 于 告诉 HTTP 框 架 ， 在 请 求 结束 时 调用 cln 的 


handler 方 法 清理 资源 。 


至 此 ，HTTP 模 块 已 经 可 以 辣 客 户 问 友 送 文件 了 。 下 面 介 绍 一 下 如 
何 文 持 多 线程 下 载 与 断 点 续 传 。 


3.8.3 ” 文 持 用 户 多 线程 下 载 和 断 点 续 传 


RFC2616 规 范 中 定义 了 range 协 议 ， 它 给 出 了 一 种 规则 使 得 客户 端 可 
以 在 一 次 请 求 中 只 下 载 完 整 文 件 的 某 一 部 分 ， 这 样 就 可 支持 客户 端 在 开 
启 多 个 线程 的 同时 下 载 一 份 文件 ， 其 中 每 个 线程 仅 下 载 文件 的 一 部 分 ， 
最 后 组 成 一 个 完整 的 文件 。range 也 支持 断 点 续 传 ， 只 要 客户 端 记 录 了 
上 次 中 断 时 已 经 下 载 部 分 的 文件 偏 移 量 ， 就 可 以 要 求 服务 器 从 断 点 处 发 
送 文 件 之 后 的 内 容 。 








Nginx 对 range 协 议 的 支持 非常 好 ， 因 为 range 协 议 主要 增加 了 一 些 
HTTP 尖 部 处 理 流程 ， 以 及 发 送 文 件 时 的 偏 移 量 处 理 。 在 第 1 章 中 曾 说 
过 ，Nginx 设 计 了 HTTP 过 滤 模 块 ， 每 一 个 请 求 可 以 由 许多 个 HTTP 过 滤 
模块 处 理 ， 而 http_range_header filter 模 块 承 是 用 来 处 理 HTTP 请 求 头 部 
range 部 分 的 ， 它 会 解析 客户 端 请 求 中 的 range 头 部 ， 最 后 告知 在 发 送 
HTTP 啊 应 包 体 时 将 会 调用 到 的 ngx_http_range_body _filter module 模 
块 ， 该 模块 会 按照 range 协 议 修改 指 辣 文件 的 ngx_buf t 绥 冲 区 中 的 











file_ pos 和 file_last 成 员 ， 以 此 实现 仅 发 送 一 个 文件 的 部 分 内 容 到 客户 
端 。 

其 实 ， 文 持 range 协 议 对 我 们 来 说 很 简单 ， 只 需要 在 发 送 前 设置 
ngx_http_request_t 的 成 员 allow_ranges 变 量 为 1 即 可 ， 之 后 的 工作 都 会 由 


HTTP 框 架 完 成 。 例 如 : 





r->allow_ranges = 1; 





这 样 ， 我 们 就 文 持 了 多 线程 下 载 和 断 点 续 传 功能 。 


3.9 用 C++ 语言 编写 HTTP 横 块 


Nginx 及 其 官方 模块 都 是 由 C 语 言 开 发 的 ， 那 么 能 不 能 使 用 C++ 语言 
来 开发 Nginx 模 块 呢 ? C 语 言 是 面 癌 过 程 的 编程 语言 ，C++ 则 是 面 问 对 象 
的 编程 语言 ， 面 癌 对 象 与 面 问 过 程 的 优 劣 这 里 暂且 不 论 ， 存 在 即 合理 。 
当 我 们 由 于 各 种 原因 需要 使 用 C++ 语言 实现 一 个 Nginx 模 块 时 《例如 ， 
茶 个 子 功能 是 用 C++ 语 言 写 成 ， 或 者 开发 团队 对 C++ 语 言 更 熟练 ， 叉 或 
者 就 是 喜欢 使 用 C++ 语言 )》 ， 尽 管 Nginx 本 身 并 没有 提供 相应 的 方法 文 
持 这 样 做 ， 但 由 于 C 语 言 与 C++ 语言 的 近 杀 特性 ， 我 们 还 是 可 以 比较 容 
易 达 成 此 目的 的 。 





首先 需要 并 清楚 相关 解决 方案 的 设计 上 思路。 


. 不 要 试图 用 C++ 编 译 器 (如 G++) 来 编译 Nginx 的 官方 代码 ， 这 
会 带 来 大 量 的 不 可 控 错误 。 正 确 的 做 法 是 仍然 用 C 编 译 器 来 编译 Neinx 官 
方 提供 的 各 模块 ， 而 用 C++ 编译 器 来 编译 用 C++ 语言 开发 的 模块 ， 最 后 
利用 C++ 向 前 兼容 C 语 言 的 特性 ， 使 用 C++ 编译 器 把 所 有 的 目标 文件 链 
接 起 来 (包括 C 编 译 器 由 Nginx 官 方 模块 生成 的 目标 文件 和 C++ 编译 器 由 
第 三 方 模块 生成 的 目标 文件 ) ， 这 样 才 可 以 正确 地 生成 二 进 制 文件 
Nginx。 


` 保证 C++ 编译 的 Nginx 模 块 与 C 编 译 的 Nginx 模 块 互 相 适应 。 所 谓 


互相 适应 就 是 C++ 模块 要 能 够 调用 Nginx 框 架 提 供 的 C 语 言 方法 ， 而 
Nginx 的 HTITP 框 架 也 要 能 够 正常 地 回调 C++ 模块 中 的 方法 去 处 理 请 求 。 


这 一 点 用 C++ 提供 的 extetn“C” 特 性 即 可 实现 。 


下 面 详 述 如 何 实 现 上 述 两 点 内 容 。 


3.9.1 ”编译 方式 的 修改 


Nginx 的 configure 脚 本 没有 对 C++ 语言 编译 模块 提供 文 持 ， 因 此 ， 修 
改编 译 方式 就 有 以 下 两 种 思路 : 





1) 修改 configure 相 关 的 脚本 。 


2) 修改 configure 执 行 完毕 后 生成 的 Makefile 文 件 。 





我 们 推荐 使 用 第 2 种 方法 ， 因 为 Nginx 的 一 个 优点 是 具备 大 量 的 第 三 
方 模块 ， 这 些 模块 都 是 基于 官方 的 configure 肢 本 而 写 的 ， 擅 自修 改 
configure 脚 本 会 导致 我 们 的 Nginx 无 法 使 用 第 三 方 模块 。 


修改 Makefile 其 实 是 很 简单 的 。 首 先 我 们 根据 3.3.2 节 介绍 的 方式 来 
执行 configure 脚 本 ， 之 后 会 生成 objs/Makefile 文 件 ， 此 时 只 需要 修改 这 
个 文件 的 3 处 即 可 实现 C++ 模 块 。 这 里 还 是 以 mytest 模 块 为 例 ， 代 码 如 
下 





CXX = g++ 

CFLAGS = -pipe -0 -W -Wall -wpointer-arith -wno-unused-parameter -Wunused-functior 
CPP = gcc -E 

LINK = $(CXX)… 


objs/addon/httpmodule/ngx_http_mytest_module.o: $(ADDON_DEPS) \\ 
../sample/httpmodule/ngx_http_mytest module.c 
$(CXX) -c $(CFLAGS) $(ALL_INCS) \ 
-0 objs/addon/httpmodule/ngx_http_mytest module.o \ 
../sample/httpmodule/ngx_http_mytest_ module.cpp:… 








下 面 解释 一 下 上 述 代 码 中 修改 的 地 方 。 


` 在 Makefile 文 件 首部 新 增 了 一 行 CXX=g++， 即 添加 了 C++ 编译 


Ns 
O 


. 把 链接 方式 LINK=$(CC) 改 为 了 LINK=$(CXX) ， 表 示 用 C++ 编译 
器 做 最 后 的 链接 。 


. 把 模块 的 编译 方式 修改 为 C++ 编译 器 。 如 果 我 们 只 有 一 个 C++ 源 
文件 ， 则 只 要 修改 一 处 ， 但 如 果 有 多 个 C++ 源 文件 ， 则 每 个 地 方 都 需要 
修改 。 修 改 方式 是 把 $(CO) 改 为 (CXX)。 





这 样 ， 编 译 方式 即 修改 完毕 。 修 改 源 文件 后 不 要 轻易 执行 configure 
脚本 ， 否 则 会 履 盖 已 经 修改 过 的 Makefile。 建 议 将 修改 过 的 Makefile 文 
件 进行 备份 ， 避 免 每 次 执行 configure 后 重新 修改 Makefile。 





@ is 确保 在 操作 系统 上 已 经 安装 了 C++ 编译 器 。 请 参照 1.3.2 


节 中 的 方式 安装 gcc-c++ 编 译 器 。 


3.9.2 ”程序 中 的 符号 转换 


C 语 言 与 C++ 语 言 最 大 的 不 同 在 于 编译 后 的 符号 有 差别 (C++ 为 了 
文 持 多 种 面 癌 对 象 特性 ， 如 重 载 、 类 等 ， 编 译 后 的 方法 名 与 C 语 言 完 全 
不 同 ) ， 这 可 以 通过 C++ 语 言 提供 的 extermm“C”{} 来 实现 符号 的 互相 识 
别 。 也 就 是 说 ， 在 C++ 语言 开发 的 模块 中 ，include 包 含 的 Nginx 官 方 头 
文件 都 需要 使 用 extern“C” 括 起 来 。 例 如 : 














extern "CcC" { 
#include <ngx_config.h> 
#include <ngx_core.h> 
#include <ngx_http.h> 

} 





这 样 就 可 以 正 帝 地 调用 Nginx 的 各 种 方法 了 。 


另外 ， 对 于 希望 Nginx 框 架 回 调 的 类 似 于 ngx_http_mytest_handler 这 
样 的 方法 也 需要 放 在 extern“C” 中 。 


了 10 小 对 


本 章 讲述 了 如 何 开发 一 个 基本 的 HTTP 模块 ， 这 里 除了 获取 请 求 的 
包 体 外 没有 涉及 异步 处 理 问题 。 通 过 本 章 的 学 习 ， 读 者 应 该 可 以 轻松 地 
编写 一 个 简单 的 HTTP 模 块 了 ， 既 可 以 获取 到 用 户 请 求 中 的 任何 信息 ， 
也 可 以 发 送 任意 的 响应 给 用 户 。 当 然 ， 处 理 方 法 必须 是 快速 、 无 阻塞 
的 ， 因 为 Nginx 在 调用 例子 中 的 ngx_http_mytest_handler 方 法 时 是 阻塞 了 
整个 Nginx 进 程 的 ， 所 以 ngx_http_mytest_handler 或 类 似 的 处 理 方法 中 是 
不 能 有 耗 时 很 长 的 操作 的 。 





第 4 章 ”配置 、error 日 志和 请 求 上 下 文 


在 开发 功能 灵活 的 Nginx 模 块 时 ， 需 要 从 配置 文件 中 获取 特定 的 信 
息 ， 不 过 ， 不 需要 再 编写 一 套 读 取 配 置 的 系统 ，Nginx 已 经 为 用 户 提供 
了 强大 的 配置 项 解析 机 制 ， 同 时 它 还 支持 “-s reload” 命 令 一 一 在 不 重启 
服务 的 情况 下 可 使 配置 生效 。4.1 节 会 回顾 第 2 章 中 http 配 置 项 的 一 些 特 
点 ，4.2 节 中 会 全 面 讨论 如 何 使 用 http 配 置 项 ， 包 括 使 用 Nginx 预 设 的 解 
析 方 法 〈 可 以 少 写 许多 代码 ) 或 者 自 定 义 配 置 项 的 解析 方式 ， 如 果 读 者 
对 其 中 较 复杂 的 配置 块 舱 套 关 系 有 疑问 ， 在 4.3 节 中 会 从 HTTP 框 染 的 实 
现 机 制 上 解释 http 配 置 项 的 模型 。 











开发 复杂 的 Nginx 模 块 时 ， 如 何 定 位 代码 上 的 问题 是 必须 考虑 的 前 
提 条 件 ， 此 时 输出 各 种 日 志 束 显得 很 关键 了 ，4.4 贡 中 会 讨论 Nginx 为 用 
户 准备 好 的 输出 日 志方 法 。 





编写 全 异步 的 HTTP 模 块 时 ， 必 须要 有 上 下 文 来 维持 一 个 请 求 的 必 
要 信息 ， 在 4.5 节 中 ， 首 先 探 讨 请 求 的 上 下 文 与 全 异步 实现 的 Nginx 服 务 
之 间 的 关系 ， 以 及 如 何 使 用 HTTP 上 下 文 ， 然 后 简单 描述 HITP 框 架 是 如 
何 管理 请 求 的 上 下 文 结构 体 的 。 





4.1 http 配 置 项 的 使 用 场景 





在 第 2 章 中 通过 多 样 化 修改 nginx.conf 文 件 中 的 配置 项 ， 实 现 了 复杂 
的 Web 服 务 器 功能 。 其 中 ，http{..:} 内 的 配置 项 最 为 复杂 ， 在 http 配 置 块 
内 还 有 server 块 、location 块 等 ， 同 一 个 配置 项 可 以 同时 出 现在 多 个 http 
块 、server 块 或 location 块 内 。 





那么 ， 如 何 解析 这 样 的 配置 项 呢 ? 在 第 3 章 中 的 mytest 例 子 中 ， 又 是 
怎样 获取 nginx.conf 中 的 配置 的 呢 ? 当 同 一 个 配置 在 http 块 、server 块 、 
location 块 中 同时 出 现时 ， 应 当选 择 哪 一 个 块 下 的 配置 呢 ? 当 多 个 不 同 
URI 表 达 式 下 的 location 都 配置 了 mytest 这 个 配置 项 ， 然 而 后 面 的 参数 值 
却 不 同时 ，Nginx 是 如 何 处 理 的 呢 ? 这 些 束 是 本 章 将 要 回答 的 问题 。 








我 们 先 来 看 一 个 例子 ， 有 一 个 配置 项 test_str， 它 在 多 个 块 内 都 出 现 
了 ， 如 下 所 示 。 








http { 
test_str main; 
server { 
listen 80; 
test_str server80,; 
location /urli { 
mytest 
test_str loci1; 


} 

lJocation /url2 { 
mytest ， 
test_str 1oc2 


} 


server { 
listen 8080; 


test_str Server8080 

Jocation /url3 { 
mytest 
test_str 1oc3 


} 





在 上 面 的 配置 文件 中 ，test_str 这 个 配置 项 在 http 块 内 出 现 的 值 为 
main， 在 监听 80 端 口 的 server 块 内 test_str 值 为 server80， 该 server 块 内 有 
两 个 location 都 是 由 第 3 章 中 定义 的 mytest 模 块 处 理 的 ， 而 且 每 个 location 
中 又 重新 设置 了 test_str 的 值 ， 分 别 为 1oc1 和 1loc2。 在 这 之 后 又 定义 了 监 
听 8080 端 口 的 server 块 ， 并 重 定义 test_str 的 值 为 server8080， 这 个 server 
块 内 定义 的 一 个 location 也 是 由 mytest 模 块 处 理 的 ， 而 且 这 个 location 内 再 
次 重 定义 了 test_str 的 值 为 loc3。 《事实 上 不 只 是 例子 中 的 server 块 可 以 藤 
套 l]ocation 块 ，location 块 之 间 还 可 以 继续 租 套 ， 这 样 test_str 的 值 就 更 复 
杂 了 ， 上 例 中 没有 出 现 location 中 进一步 反复 授 套 location 的 场景 。 在 
4.3.3 节 讨论 HTTP 框 架 如 何 合并 配置 项 时 涉及 了 location 块 的 反复 散 套 问 


题 ， 请 读者 注意 。) 





在 这 段 很 短 的 配置 中 ，mytest 模 块 将 会 处 理 两 个 监听 端口 上 建立 的 
TCP 连 接 ， 以 及 3 种 HTTP 请 求 ， 请 求 的 URL 分 别 对 应 
着 /url1、mrl2、Amrl3。 假 设 mytest 模 块 必 须 取出 test_str 配 置 项 的 参数 ， 
可 是 在 以 上 的 例子 中 test_str 出 现 了 6 个 不 同 的 参数 值 ， 分 别 为 main、 
server80、server8080、locl1、loc2、loc3， 那 么 在 mytest 模 块 中 我 们 取 到 
的 test_str 值 以 哪 一 个 为 准 呢 ? 








事实 上 ，Nginx 的 设计 是 非常 灵活 的 (实际 上 这 是 第 10 章 将 要 介绍 
的 HTTP 框 架设 计 的 ) ， 它 在 每 一 个 http 块 、server 块 或 location 块 下 ， 都 
会 生成 独立 的 数据 结构 来 存放 配置 项 。 因 此 ， 我 们 允许 当 用 户 访问 的 请 
求 不 同时 (如 请 求 的 URL 分 别 是 /unl1、/md2、/url3)〉 ， 配 置 项 test_str 可 
以 具有 不 同 的 值 。 那 么 ， 当 请 求 是 /arl1 时 ，test_str 的 值 应 当 是 location 块 
下 的 loc1， 还 是 这 个 location 所 属 的 server 块 下 的 server80， 又 或 者 是 其 所 
属 http 块 下 的 值 main 呢 ?完全 由 mytest 模 块 自己 决定 ， 我 们 可 以 定义 这 
个 行为 。 下 面 在 4.2 节 中 将 说 明 如 何 灵 活 地 使 用 配置 项 ， 在 4.3 贡 中 将 探 
讨 Nginx 实 际 上 是 如 何 实现 http 配 置 功能 的 。 








4.2 怎样 合用 http 配 置 


事实 上 ， 在 第 3 章 中 已 经 使 用 过 mytest 配 置 项 ， 只 不 过 当时 mytest 配 
置 项 是 没有 值 的 ， 只 是 用 来 标识 当 ]location 块 内 出 现 mytest 配 置 项 时 就 启 
用 mytest 模 块 ， 从 而 处 理 匹配 该 location 表 达 式 的 用 户 请 求 。 本 章 将 由 易 
到 难 来 前 述 HTTP 模 块 是 怎样 获得 感 兴 趣 的 配置 项 的 。 











处 理 http 配 置 项 可 以 分 为 下 面 4 个 步骤 : 
1) 创建 数据 结构 用 于 存储 配置 项 对 应 的 参数 。 
2) 设 定 配置 项 在 nginx.conf 中 出 现时 的 限制 条 件 与 回调 方法 。 


3) 实现 第 2 步 中 的 回调 方法 ， 或 者 使 用 Nginx 框 以 预 设 的 14 个 回调 
方法 。 


4) 合并 不 同 级 别 的 配置 块 中 出 现 的 同名 配置 项 。 





不 过 ， 这 4 个 步骤 如 何 与 Nginx 有 机 地 结合 起 来 呢 ? 就 是 通过 第 3 章 
中 介绍 过 的 两 个 数据 结构 ngx_http_module_t 和 ngx_command_t， 它 们 都 
是 定义 一 个 HTTP 模 块 时 不 可 或 缺 的 部 分 。 





4.2.1 分 配 用 于 保存 配置 参数 的 数据 结构 


首先 需要 创建 一 个 结构 体 ， 其 中 包含 了 所 有 我 们 感 兴 趣 的 参数 。 为 
本 说明 14 种 预 设 配 置 项 的 解析 方法 ， 我 们 将 在 这 个 结构 体 中 定义 14 个 成 
员 ， 存 储 感 兴趣 的 配置 项 参数 。 例 如 : 





typedef struct { 


ngx_str_t my_str; 
ngx_int_t my_num; 
ngx_flag_t my_flag; 
size_t my_size; 
ngx_array_t* my_str_array; 
ngx_array_t* my_keyval,; 
off_t my_off; 
ngx_msec_t my_msec; 
time_t my_sec,; 
ngx_bufs_t my_bufs; 
ngx_uint_t my_enum_seq; 
ngx_uint_t my_bitmask; 
ngx_uint_t my_access; 
ngx_path_t* my_path; 


} ngx_http_mytest_conf_t; 








ngx_http_mytest_conf_t 中 的 14 个 成 员 存 储 的 配置 项 都 不 相同 ， 读 者 
可 暂时 忽略 上 面 ngx_http_mytest_conf_t 结 构 中 一 些 没 见 过 的 Nginx 数 据 


结构 ， 这 些 将 在 4.2.3 市 中 介绍 。 





为 什么 要 这 么 严格 地 用 一 个 结构 体 来 存储 配置 项 的 参数 值 ， 而 不 是 
随意 地 定义 几 个 全 局 变量 来 存储 它们 呢 ? 这 就 要 回 到 4.1 节 中 例子 的 使 
用 场景 了 ， 多 个 location 块 (或 者 http 块 、server 块 ) 中 的 相同 配置 项 是 
允许 同时 生效 的 ， 也 束 是 说 ， 我 们 刚刚 定义 的 ngx_http_mytest_conf _t 结 
构 必 须 在 Nginx 的 内 存 中 保存 许多 份 。 事 实 上 ，HTTP 框 架 在 解析 
nginx.conf 文 件 时 只 要 遇 到 http{}、server{} 或 者 location{} 配 置 块 就 会 立 
刻 分 配 一 个 新 的 ngx_http_mytest_conf_t 结 构 体 。 因 此 ，HTTP 模 块 感 兴 














趣 的 配置 项 需要 统一 地 使 用 一 个 struct 结 构 体 来 保存 〈 否 则 HTTP 框 架 无 
法 管理 ) ， 如 果 nginx.conf 文 件 中 在 http{} 下 有 多 个 server{} 或 者 
location{}， 那 么 这 个 struct 结 构 体 在 Nginx 进 程 中 就 会 存在 多 份 实例 。 





Nginx 怎 样 管理 我 们 自 定 义 的 存储 配置 的 结构 体 
ngx_http_mytest_conf_t 呢 ? 很 简单 ， 通 过 第 3 章 中 曾经 提 到 的 
ngx_http_module_t 中 的 回调 方法 。 下 面 回顾 一 下 ngx_http_module_t 的 定 
> 





typedef struct { 
ngx_int_t (*preconfiguration)(ngx_conf_t *cf); 
ngx_int_t (*postconfiguration)(ngx_conf_t *cf); 
void *(*create main conf)(ngx_conf_t *cf); 
char * 
void * 


*init main_ conf)(ngx_conf_t *cf, void *conf); 
*create_srv_conf)(ngx_conf_t *cf); 

char *(*merge_srv_conf)(ngx_conf_t *cf, void *prev, void *conf); 

void *(*create_ loc conf)(ngx_conf_t *cf); 

char *merge_loc_conf)(ngx_conf_t *cf, void *prev, void *conf); 
} ngx_http_module_t; 


* 
一 一 一 一 一 一 





其 中 ，create_main _ conf、create_SrV_conf、create_ loc_conf 这 3 个 回 
调 方 法 负责 把 我 们 分 配 的 用 于 保存 配置 项 的 结构 体 传递 给 HTTP 框 架 。 
下 面 解释 一 下 为 什么 不 是 定义 1 个 而 是 定义 3 个 回调 方法 。 





HTTP 框 架 定 义 了 3 个 级 别 的 配置 main、srv、loc， 分 别 表 示 直 接 出 
现在 http{}、server{}、location{} 块 内 的 配置 项 。 当 nginx.conf 中 出 现 
http{} 时 ，HTTP 框 架 会 接管 配置 文件 中 http{} 块 内 的 配置 项 解析 ， 之 后 
的 流程 可 以 由 4.3.1 节 中 的 图 4-1 来 了 解 。 当 遇 到 http{.….} 配 置 块 时 ，HTTP 
框架 会 调用 所 有 HTTP 模 块 可 能 实现 的 create_main_conf、 








create_srv_conf、create_loc_conf 方 法 生成 存储 main 级 别 配 置 参数 的 结构 
体 ; 在 遇 到 server{..:} 块 时 会 再 次 调用 所 有 HTTP 模 块 的 create_srv_conf、 
create_loc_conf 回 调 方法 生成 存储 srv 级 别 配 置 参数 的 结构 体 ; 在 遇 到 

location{...} 时 则 会 再 次 调用 create_ loc_conf 回 调 方法 生成 存储 loc 级 别 配 
置 参数 的 结构 体 。 因 此 ， 实 现 这 3 个 回调 方法 的 意义 是 不 同 的 ， 例 如 ， 

对 于 mytest 模 块 来 说， 在 http{} 块 内 只 会 调用 1 次 create_main_conf， 而 

create_loc_conf 可 能 会 被 调用 许多 次 ， 也 就 是 有 许多 个 由 create_loc_conf 
生成 的 结构 体 。 


普通 的 HTTP 模 块 往往 只 实现 create_ loc_conf 回 调 方法 ， 因 为 它们 只 
关注 匹配 某 种 URL 的 请 求 。 我 们 的 mytest 例 子 也 是 这 样 实现 的 ， 这 里 实 


现 create_loc_conf 的 是 ngx_http_mytest_create_loc_conf 方 法 ， 如 下 所 示 。 





static void* ngx_http_mytest_create_loc conf(ngx_conf_t *cf) 





ngx_http_mytest_conf t *mycf; 
mycf = (ngx_http_mytest conf_t *)ngx_pcalloc(cf->pool, sizeof(ngx_http_mytest_‘ 
if (mycf == NULL) { 

return NULL; 
} 
mycf->my_flag = NGX_CONF_UNSET ; 
mycf->my_num = NGX_CONF_UNSET ; 
mycf->my_str_array = NGX_CONF_UNSET_PTR; 
mycf->my_keyval = NULL; 
mycf->my_off = NGX_CONF_UNSET ; 
mycf->my_msec = NGX_CONF_UNSET_MSEC; 
mycf->my_sec = NGX_CONF_UNSET ; 
mycf->my_size = NGX_CONF_UNSET_SIZE; 
return mycf,; 











上 述 代码 中 对 一 些 配置 参数 设置 了 初始 值 ， 这 是 为 了 14 个 预 设 方法 
准备 的 ， 下 面 会 解释 为 什么 要 这 样 赋值 。 


4.2.2” 设 定 配置 项 的 解析 方式 


下 面 详细 介绍 在 读 取 HTTP 配 置 时 是 如 何 使 用 ngx_command_t 结 构 
的 ， 首 先 回顾 一 下 第 3 章 中 曾经 提 到 过 的 定义 ， 再 详细 介绍 每 个 成 员 的 


Be 
蕊 义 。 





struct ngx_command _s { 
ngx_str_t name; 
ngx_uint_t type; 
char *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf); 
ngx_uint_t conf; 
ngx_uint_t offset 
void *post; 





(1) ngx_str_t name 
其 中 ，name 是 配置 项 名 称 ， 如 4.1 节 例子 中 的 “test_str”。 
(2) ngx_uint t type 


其 中 ，type 决 定 这 个 配置 项 可 以 在 哪些 块 〈 如 http、server、 
location、 计 、upstream 块 等 ) 中 出 现 ， 以 及 可 以 携带 的 参数 类 型 和 个 数 
等 。 表 4-1 列 出 了 设置 http 配 置 项 时 type 可 以 取 的 值 。 注 意 ，type 可 以 同 
时 取 表 4-1 中 的 多 个 值 ， 各 值 之 间 用 | 符号 连接 ， 例 如 ，type 可 以 取 值 为 
NGX_ HTTP MAIN CONFINGX _ HTTP_ SRV_CONFINGX HTTP LOC _C 


表 4-1 ngx_command_t 结 构 体 中 type 成 员 的 取 值 及 其 意 》 


ES 吉文 


- 般 由 NGX_CORE _ MODULE 类 型 的 核心 模块 使 用 ， 
仅 与 下 面 的 NGX_MAIN_CONF 同时 设置 ， 表 示 模 块 需要 
解析 不 属于 任何 内 的 全 局 配置 项 。 它 实际 上 会 指定 set 
方法 里 的 第 3 个 参数 conf 的 值 ， 使 之 指向 每 个 模块 解析 全 
局 配置 项 的 配置 结构 体 ” 
目前 未 使 用 ， 设 置 与 香 均 无 意义 
配置 项 可 以 出 现在 全 局 配置 中 ， 即 不 属于 任何 {} 配置 块 
配置 项 可 以 出 现在 events {3 块 内 
配置 项 可 以 出 现在 mail 全 块 或 者 imap {3 块 内 


配置 项 可 以 出 现在 server f} 块 内 ， 然 而 该 server 他 块 必 
SRV 站 
须 属 于 mail 0 块 或 者 imap 呈 块 


卫生 大 可 以 中 现在 Wip 人 志 


ee 出 现在 server 们 块 内 ， 然 而 该 server 块 必须 

项 可 以 在 哪些 ti 可 以 出 现在 locati 二 es 
eg 本 可 以 二 现在 onen (其 肉 。 伏 而 该 iocnion 忆 
了 和 upstream f} 块 内 。 然 而 该 upstream 块 


配置 项 可 以 出 现在 location 块 内 的 这 中 块 中 。 目 前 仅 有 
rewrite 模块 会 合用， 该 诺 块 必须 属于 http 1} 块 


配置 项 可 以 出 现在 limit except 由 块 内 ， 然 而 该 limit 
except 块 必须 属于 http 和 个 块 


配置 项 不 携带 任何 参数 
配置 项 必须 携带 1 个 参数 
配置 项 必须 携带 2 个 参数 
忆 秆 项 必须 携带 3 个 参数 
配置 项 必须 携带 4 个 参数 
i 配置 项 必须 携带 5 个 参数 
pe 配置 项 必须 携带 6 个 参数 
配置 项 必须 携带 7 个 参数 
配置 项 可 以 携带 1 个 参数 或 2 个 参数 
配置 项 可 以 携带 1 个 参数 或 3 个 参数 
配置 项 可 以 携带 2 个 参数 或 3 个 参数 
配置 项 可 以 携带 1 ~ 3 个 参数 
配置 项 可 以 携带 1 ~ 4 个 参数 





处 理 配 辕 项 时 获取 |NGX_DIRECT_CONF 
当前 配置 块 的 方式 


NGX_HTTP_LIF_ CONF 


NGX_HTTP_LMT_CONF 


type 类 型 


过 工作 
,|NGX CONF 2MORE 配置 项 携带 的 参数 个 数 必须 超过 2 个 
限制 配置 项 后 的 参 


数 出 现 的 形式 





NGX CONF ARGS NUMBER 目前 未 使 用 ， 无 意义 

配置 项 定义 了 一 种 新 的 合 块 。 例 如 ，http、server、 
NGX CONF BLOCK location 等 配置 ,它们 的 type 都 必须 定义 为 NGX_CONF_ 
BLOCK 


NGX_CONF_ANY 不 验证 配置 项 携带 的 参数 个 数 


配置 项 携带 的 参数 只 能 是 1 个， 并 且 参 数 的 值 只 能 是 on 


或 者 off 


NGX CONF 1MORE 配置 项 携带 的 参数 个 数 必 须 超 ; 





NGX CONF FLAG 


1 


表示 当前 配置 项 eis 块 中 (包括 不 属于 任何 
块 的 全 局 配置 )， 它 仅 用 于 配 A 其 他 I 配置 项 使 用 。type 中 未 
加 NGX_CONF MULII 时 ， 如 果 一 个 配置 项 出 现在 type 
成 员 未 标明 的 配置 块 中 ,那么 Nginx 会 认为 该 配置 项 非法 ， 
最 后 将 导致 Nginx 局 动 失 败 。 但 如 果 type 中 加 入 了 NGX _ 
NGX CONF _ MULTI CONF_ MULTI， 则 认为 该 配置 项 一 定 是 合法 的 ， 然 而 又 
会 有 两 种 不 同 的 结果 : 中 如 果 配 置 项 出 现在 type 指示 的 块 
中 ， 则 会 调用 set 方 法 解析 配置 项 ; 人 @@ 如 果 配 置 项 没有 出 现 
在 type 指示 的 块 中 ， 则 不 对 该 配置 项 做 任何 处 理 。 因 此 ， 
NGX_CONF_MULTI 会 使 得 配置 项 出 现在 未 知 块 中 时 不 会 
出 错 。 目 前， 还 没有 官方 模块 使 用 过 NGX_CONF_MULTI 





每 个 进程 中 都 有 一 个 唯一 的 ngx_cycle_t 核 心 结 构 体 ， 它 有 一 个 成 
员 conf_ctx 维 护 着 所 有 模块 的 配置 结构 体 ， 其 类 型 是 void*+***。conf_ctx 
意义 为 首先 指向 一 个 成 员 辟 为 指针 的 数组 ， 其 中 每 个 成 员 指 针 又 指向 另 
外 一 个 成 员 导 为 指针 的 数组 ， 第 2 个 子 数 组 中 的 成 员 指 针 才 会 指向 各 模 
块 生成 的 配置 结构 体 。 这 正 是 为 了 事件 模块 、http 模 块 、mail 模 块 而 设 
计 的 ， 第 9、10 章 都 有 详 述 ， 这 有 利于 不 同 于 NGX_CORE_MODULE 类 


型 的 特定 模块 解析 配置 项 。 然 而 ，NGX_CORF_MODUILE 类 型 的 核心 
模块 解析 配置 项 时 ， 配 置 项 一 定 是 全 局 的 ， 不 会 从 属于 任何 们 配置 块 
的 ， 它 不 需要 上 述 这 种 双 数 组 设计 。 解 析 标 识 为 NGX_DIRECT_CONF 


类 型 的 配置 项 时 ， 会 把 void** 冰 类 型 的 conf_ctx 强 制 转换 为 void**， 也 就 
是 说 ， 此 时 ， 在 conf_ctx 指 向 的 指针 数组 中 ， 每 个 成 员 指 针 不 再 指向 其 
他 数组 ， 直 接 指 向 核心 模块 生成 的 配置 结构 体 。 因 此 ， 

NGX_DIRECT_CONF 仅 由 NGX_CORF_MODUILE 类 型 的 核心 模块 使 


用 ,而 且 配 置 项 只 应 该 出 现在 全 局 配置 中 。 


@ 注意 ”如 果 HTTP 模 块 中 定义 的 配置 项 在 nginx.conf 配 置 文件 中 
实际 出 现 的 位 置 和 参数 格式 与 type 的 意义 不 符 ， 那么 Nginx 在 启动 时 会 报 
错 。 


(3) char*(*set)(ngx_conf t*cf,ngx_command_t*cmd,void*conf) 





关于 set 回 调 方法 ， 在 第 3 章 中 人 处理 mytest 配 置 项 时 已 经 使 用 过 ， 其 
中 mytest 配 置 项 是 不 带 参 数 的 。 如 果 处 理 配置 项 ， 我 们 既 可 以 自己 实现 
一 个 回调 方法 来 处 理 配置 项 〈4.2.4 节 中 会 举例 说 明 如 何 自 定义 回调 方 
法 ) ， 也 可 以 使 用 Nginx 预 设 的 14 个 解析 配置 项 方法 ， 这 会 少 写 许多 代 
码 ， 表 4-2 列 出 了 这 些 预 设 的 解析 配置 项 方法 。 我 们 将 在 4.2.3 节 中 举例 
说 明 这 些 预 设 方法 的 使 用 方式 。 








表 4-2 预 设 的 14 个 配置 项 解析 方法 


预 设 方法 名 


ngx_conf set flag slot 


ngx_ conf set str Slot 


ngx_conf set_ str array slot 


ngx_conf set keyval silot 


ngx_conf set num slot 


ngx_ conf set size slot 


ngx_cont set_ off slot 


ngx_conf set_ msee slot 


ngx_conf set sec slor 


ngx_conf set bufs slot 


行 为 

如 果 nginx.conf 交 件 中 茜 个 配置 项 的 参数 是 on 或 者 off { 即 希望 配置 项 表达 打 
开 或 者 关闭 革 个 功能 的 意思 )， 而 且 在 Nginx 模块 的 代码 中 使 用 ngx_flag (变量 来 
保存 这 个 配置 项 的 参数 ， 就 可 以 将 set 回调 方法 设 为 ngx_conf set_flag slot。 当 
nginx.conf 文件 中 参数 是 on 时， 代码 中 的 ngx_flag_t 类 型 变量 将 设 为 1， 参数 为 
o 信 时 则 设 为 0 

如 果 配 置 项 后 上 只 有 1 个 参数 .同时 在 代码 中 我 们 希望 用 ngx_str t+ 类 地 的 变量 来 
保存 这 个 配置 项 的 参数 ， 则 可 以 使 用 ngx_conf set_str_slot 方法 

如 果 这 个 配置 项 会 出 现 多 次 ， 每 个 配置 项 后 面 都 跟着 1 个 参数 ， 而 在 程序 中 我 
们 希望 仅 用 一 个 ngx_array_t 动态 数组 (用 法 见 7.3 节 ) 来 存储 所 有 的 参数 。 且 数 
组 中 的 每 个 参数 都 以 ngx_str ! 来 存储 ， 那 么 预 设 的 ngx_conf set_ str_array slot 方 
法 可 以 帮 我 们 做 到 

与 ngx_conf set_str_array_slot 类 似 ， 也 是 用 一 个 ngx_array { 数 组 来 存储 所 有 
同名 配置 项 的 参数 。 只 是 每 个 配置 项 的 参数 不 再 只 是 1 个， 而 必须 基 两 个 ， 且 以 
“ 配 先 项 名 关键 字 值 ;” 的 形式 出 现在 nginx.conf 文件 中 ， 同 时 ，ngx_conf set_ 
keyval slot 将 把 这 些 配 蚂 项 转化 为 数组 ， 其 中 每 个 元 素 都 存储 着 key/value 键 值 对 

配置 项 后 必须 携带 1 个 参数 ， 且 只 能 是 数字 。 存 储 这 个 参数 的 变量 必须 是 整 型 

配置 项 后 必须 携带 1 个 参数， 表示 空间 大 小 ， 可 以 是 一 个 数字 ， 这 时 表示 字 节 
数 ( Byte)。 如 果 数 字 后 跟着 k 或 者 K， 就 表示 Kilobyte，1KB=1024B ; 如 果 数 字 
后 跟着 m 或 者 M， 就 表示 Megabyte、1MB=1024KB。ngx_conf _set_size_slot 解析 
后 将 把 配置 项 后 的 参数 转化 成 以 字 节 数 为 单位 的 数字 

配置 项 后 必须 携带 1 个 参数 ， 表 示 空 间 上 的 偏 移 晤 。 它 与 设置 的 参数 非常 类 似 ， 
其 参数 是 一 个 数字 时 表示 Byte， 也 可 以 在 后 而 加 单位 .但 与 ngx_conf set_size_ 
slot 不 同 的 是 。 数 字 后 面 的 单位 不 仅 可 以 是 kk 或 者 K、m 或 者 M， 还 可 以 是 g 或 
者 G， 这 时 表示 Gigabyte，1GB=1024MB。ngx_conf set_off_slot 解析 后 将 把 配置 
项 后 的 参数 转化 成 以 字 节 数 为 单位 的 数字 

配置 项 后 必须 携带 1 个 参数 ， 表 示 时 间 。 这 个 参数 可 以 在 数字 后 面 加 单位 ， 如 
果 单 位 为 s 或 者 没有 任何 单位 ， 那 么 这 个 数字 表示 秒 ;， 如 果 单 位 为 m。 则 表示 
分 钟 ，1m=60s ; 如 果 单 位 为 h、 则 表示 小 时 ，1h=60m ; 如 果 单 位 为 d， 则 表示 
天 ，1d=24h ; 如 果 单 位 为 w， 则 表示 周 ，1w=7d ; 如 果 单 位 为 M， 则 表示 月 ， 
1M=30d ; 如 果 单 位 为 y， 则 表示 年 ，1y=365d。ngx_conf _set_msec_slot 解析 后 将 
把 配置 项 后 的 参数 转化 成 以 毫秒 为 单位 的 数字 

与 ngx_conf set_msec_slot 非常 类 似 ， 唯 一 的 区 别 是 ngx_conf set_ msec_slot 解 
析 后 将 把 配置 项 后 的 参数 转化 成 以 毫秒 为 单位 的 数字 ， 而 ngx_conf Set sec_slot 
解析 后 会 把 配置 项 后 的 参数 转化 成 以 秒 为 单位 的 数字 

配置 项 后 必须 携带 一 两 个 参数 .第 1 个 参数 是 数字 ， 第 2 个 参数 表示 空间 大 小 。 
例如 ，”gzip_buffers 4 8k;”( 通 常用 来 表示 有 多 少 个 ngx_buf Tt 缓冲 区 )， 其 中 第 1 
个 参数 不 可 以 携带 任何 单位 ， 第 2 个 参数 不 带 任何 单位 时 表示 Byte， 如 果 以 k 或 
者 K 作为 单位 ， 则 表示 Kilobyte， 如 果 以 m 或 者 M 作为 单位 ， 则 表示 Megabyte。 
ngx_conf set_bufs_slot 解析 后 会 把 配置 项 后 的 两 个 参数 转化 成 ngx_bufs t+ 结构 体 
下 的 两 个 成 员 。 这 个 配置 项 对 应 于 Nginx 报喜 欢 用 的 多 缓冲 区 的 解决 方案 ( 如 接 
收 连接 对 映 发 来 的 TCP 流 ) 


预 设 方法 名 行 为 

配置 项 后 必须 携 基 ee 1 个 参数 ， 其 取 值 范围 必须 是 我 们 设 定 好 的 字符 串 之 一 (就 
像 C 语言 中 的 枚 举 一 样 )。 首 先 ， 我们 要 用 ngx_conf_enum t 结构 定义 配置 项 的 取 
值 范围 ， 并 设 定 每 人 1 [对 应 的 序列 号 。 然 后 ，ngx_conf set_enum slot 将 会 把 配置 
项 参数 转化 为 对 应 的 序列 号 

与 ngx_conf set_ bitmask slot 类 似 ， 配 置 项 后 必须 携带 1 个 参数 ， 其 取 值 范围 必 
须 是 设 定好 的 字符 串 之 一 。 首 先 ， 我 们 要 用 ngx_conf bitmask t 结构 定义 配置 项 
的 取 值 范围 ， 并 设 定 每 个 值 对 应 的 比特 位 。 注 意 ， 每 个 值 所 对 应 的 比特 位 都 要 不 
同 。 然 后 ngx_conf _set_bitmask_slot 将 会 把 配置 项 参数 转化 为 对 应 的 比特 位 

这 个 方法 用 于 设置 目录 或 者 文件 的 读 写 权限 。 配 置 项 后 可 以 携带 1 ~ 3 个 参数 ， 
可 以 是 如 下 形式 : user:rw group:rw all:rw。 注 意 ， 它 的 意义 与 Linux 上 文件 或 者 
ngx conf set access slot 日 录 的 权限 意义 是 一 致 的 ， 但 是 user/group/all 后 面 的 权限 只 可 以 设 为 rw ( 读 / 写 ) 
或 者 rf (只 读 ), 不 可 以 有 其 他 任何 形式 ， 如 Ww 或 者 IX 等 。ngx_conf set access_ 
slot 将 会 把 这 些 参数 转化 为 一 个 整 型 

这 个 方法 用 于 设置 路 径 ， 配 置 项 后 必须 携带 1 个 参数 ,表示 1 个 有 意义 的 路 径 
ngx_conf set_path_slot 将 会 把 参数 转化 为 ngx 结构 


ngx conf set enum slot 





ngx_ conf set_bitmask_ slot 





ngx conf set path slot 


(4) ngx_uint t conf 


conf 用 于 指示 配置 项 所 处 内 存 的 相对 偏 移 位 置 ， 仪 在 type 中 没有 设 
置 NGX_DIRECT_CONF 和 NGX_MAIN_CONF 时 才 会 生效 。 对 于 HTTP 
模块 ，conf 是 必须 要 设置 的 ， 它 的 取 值 范围 见 表 4-3。 


表 4-3 ngx_command ft 结 构 中 的 conf 成 员 在 HTTP 模 块 中 的 取 值 及 其 意 》 





conf 在 HTTP 模块 中 的 取 值 意 义 
NGX _HTTP MAIN CONF OFFSET 使 用 create_main_conf 方 法 产生 的 结构 体 来 存储 解析 出 的 配置 项 参数 
NGX HTTP SRV_ CONF OFFSET 使 用 create_srv_conf 方 法 产生 的 结构 体 来 存储 解析 出 的 配置 项 参数 
NGX HTTP LOC CONF OFFSET 使 用 create loc_conf 方法 产生 的 结构 体 来 存储 解析 出 的 配置 项 参数 





为 什么 HTTP 模 块 一 定 要 设置 conf 的 值 呢 ? 因为 HTTP 框架 可 以 使 用 
预 设 的 14 种 方法 自动 地 将 解析 出 的 配置 项 写 入 HTTP 模 块 代码 定义 的 结 
构 体 中 ， 但 HTTP 模 块 中 可 能 会 定义 3 个 结构 体 ， 分 别 用 于 存储 main、 


SrV、loc 级 别 的 配置 项 〈 对 应 于 create_main_ conf、create_Srv_conf、 
create_loc_conf 方 法 创建 的 结构 体 ) ， 而 HITP 框 架 自 动 解 析 时 需要 知道 
应 把 解析 出 的 配置 项 值 写 入 哪个 结构 体 中 ， 这 将 由 conf 成 员 完成 。 


此 ， 对 conf 的 设置 是 与 ngx_http_module_t 实 现 的 回调 方法 (在 
4.2.1 节 中 介绍 ) 相关 的 。 如 果 用 于 存储 这 个 配置 项 的 数据 结构 是 由 
create_main_conf 回 调 方法 完成 的 ， 那 么 必须 把 conf 设 置 为 
NGX_HTTP MAIN_CONF_OFFSET。 同 样 ， 如 果 这 个 配置 项 所 属 的 数 
据 结 构 是 由 create_srv_conf 回 调 方法 完成 的 ， 那 么 必须 把 conf 设 置 为 
NGX_HTTP_ SRV_CONF_OFFSET。 可 如 果 create_ loc_conf 负 责 生 成 存 
储 这 个 配置 项 的 数据 结构 ， 就 得 将 conf 设 置 为 
NGX_HTTP LOC_CONF_OFFSET。 








目前 ， 功 能 较为 简单 的 HITP 模 块 都 只 实现 了 create_ loc_conf 回 调 方 
法 ， 对 于 http{}、server{} 块 内 出 现 的 同名 配置 项 ， 都 是 并 入 某 个 
location{} 内 create_loc_conf 方 法 产生 的 结构 体 中 的 (在 4.2.5 节 中 会 详 述 
如 何 合并 配置 项 ) 。 当 我 们 和 希望 同时 出 现在 http{}、server{}、location{} 
块 的 同名 配置 项 ， 在 HTTP 模块 的 代码 中 保存 于 不 同 的 变量 中 时 ， 就 需 
要 实现 create_main_conf 方 法 、create_srv_conf 方 法 产生 新 的 结构 体 ， 从 
而 以 不 同 的 结构 体 独立 保存 不 同 级 别 的 配置 项 ， 而 不 是 全 部 合并 到 某 个 
location 下 create_loc_conf 方 法 生成 的 结构 体 中 。 





(5) ngx_uint t offset 





offset 表 示 当 前 配置 项 在 整个 存储 配置 项 的 结构 体 中 的 偏 移 位 置 
(以 字 节 (Byte) 为 单位 ) 。 举 个 例子 ， 在 32 位 机 器 上 ，int《〈 整 型 ) 类 
型 长 度 是 4 字 节 ， 那 么 看 下 面 这 个 数据 结构 : 





typedef struct { 
int a; 
int b; 
int c; 

} test_stru; 











如 果 要 处 理 的 配置 项 是 由 成 员 b 来 存储 参数 的 ， 那 么 这 时 b 相 对 于 
test_stru 的 偏 移 量 就 是 4;: 如 果 要 处 理 的 配置 项 由 成 员 c 来 存储 参数 ， 那 
么 这 时 c 相 对 于 test_stru 的 偏 移 量 就 是 8。 








实际 上 ， 这 种 计算 工作 不 用 用 户 自己 来 做 ， 使 用 offsetof 宏 即 可 实 
现 。 例如， 在 上 例 中 取 b 的 偏 移 量 时 可 以 这 么 做 ; 








offsetof(test_stru, b) 








其 中 ，offsetof 中 第 1 个 参数 是 存储 配置 项 的 结构 体 名 称 ， 第 2 个 参数 
是 这 个 结构 体 中 的 变量 名 称 。offsetof 将 会 返回 这 个 变量 相对 于 结构 体 的 


偏 移 量 。 





印证 示 “offsetof 这 个 宏 是 如 何 取得 成 员 相对 结构 体 的 偏 移 量 的 
呢 ? 其 实 很 简单 ， 它 的 实现 类 似 于 : #define offsetof(type,membe?) 


(Size_D&c(((type90O)->membenD。 可 以 看 到 ，offsetof 将 0 地 址 转换 成 type 结 构 


体 类 型 的 指针 ， 并 在 访问 membet 成 员 时 取得 membet 成 员 的 指针 ， 这 个 
指针 相对 于 0 地 址 来 说 自然 就 是 成 员 相 对 于 结构 体 的 偏 移 量 了 。 


设置 offset 有 什么 作用 呢 ? 如 果 使 用 Nginx 预 设 的 解析 配置 项 方法 ， 
就 必须 设置 offset， 这 样 Nginx 首 先 通 过 conf 成 员 找 到 应 该 用 哪个 结构 体 
来 存放 ， 然 后 通过 offset 成 员 找到 这 个 结构 体 中 的 相应 成 员 ， 以 便 存 放 
该 配置 。 如 果 是 自 定义 的 专用 配置 项 解析 方法 (只 解析 某 一 个 配置 
项 ) ， 则 可 以 不 设置 offset 的 值 。 读 者 可 以 通过 4.3.4 节 来 了 解 预 设 配置 
项 解析 方法 是 如 何 使 用 offset 的 。 





(6) void*post 
post 指 针 有 许多 用 途 ， 从 它 被 设计 成 void* 就 可 以 看 出 。 


如 果 自 定义 了 配置 项 的 回调 方法 ， 那 么 post 指 针 的 用 途 完 全 由 用 户 
来 定义 。 如 果 不 使 用 它 ， 那 么 随意 设 为 NULL 即 可 。 如 果 想 将 一 些 数据 
结构 或 者 方法 的 指针 传 过 来 ， 那 么 使 用 post 也 可 以 。 





如 果 使 用 Nginx 预 设 的 配置 项 解析 方法 ， 束 需要 根据 这 些 预 设 方法 
来 决定 post 的 使 用 方式 。 表 4-4 说 明了 post 相 对 于 14 个 预 设 方法 的 用 途 。 


表 4-4 ngx_command_t 结 构 中 post 的 取 值 及 其 意义 


post 的 使 用 方式 


可 以 选择 是 否 实 现 。 如 果 设 为 NULL， 则 表示 不 实现 ， 
ngx_conf post t 结构 的 指针 。ngx_conf post t 中 包含 一 个 方法 指针 ， 
当前 配置 项 完毕 后 ， 需 要 回调 这 个 方法 


表示 当前 配置 项 的 参数 必须 设置 为 ngx_conf 


使 用 ngx_conf set_enum_slot 时 必须 设置 定 


指 回 ngx_conf enum t 数 组 ， 
enum t 规定 的 值 (类 似 枚 举 ) 
义 1 个 ngx_conf enum tt 数组， 并 将 post 成 员 指 回 该 数组 


江 尼 ， 


指 问 ngx_conf bitmask t 数组， 表示 当前 配置 项 的 参数 必须 设置 为 ngx_conf_ 
bitmask_t 规定 的 值 (类 似 枚 举 )。 注 意 ， 使 用 ngx_conf set_bitmask_slot 时 必须 设 
置 定 义 1 个 ngx_conf bitmask t 数 组， 并 将 post 成 员 指 向 该 数组 





无 任何 用 处 


适用 的 预 设 配置 项 解析 方法 
ngx conf set flag slot 
ngx conf set str slot 


ngx conf set str array_slot 





ngx conf set keyval slot 
ngx conf set num slot 
ngx conf set size slot 
ngx conf set off slot 
ngx conf set msec slot 


ngx conf set_sec slot 


ngx conf set _ enum slot 


ngx conf set bitmask slot 





ngx conf set bufs slot 
ngx_conf set path slot 


ngx conf set access slot 


可 以 看 到 ， 有 9 个 预 设 方法 在 使 用 时 post 是 可 以 设置 为 
ngx_conf_post_t 结 构 体 来 使 用 的 ， 先 来 看 看 ngx_conf_post_t 的 定义 。 





typedef char *(*ngx_conf_post_handler_pt) (ngx_conf_t *cf, 
void *data, void *conf); 
typedef struct { 
ngx_conf_post_handler_pt 
} ngx_conf_post_t; 


post_handler; 





如 果 需 要 在 解析 完 配 置 项 〈 表 4-4 中 列 出 的 前 9 个 预 设 方法 ) 后 回调 
某 个 方法 ， 就 要 实现 上 面 的 ngx_conf_post_handler_pt， 并 将 包含 


post_handler 的 ngx_conf_post_t 结 构 体 传 给 post 指 针 。 


目前 ，ngx_conf_ post_t 结 构 体 提供 的 这 个 功能 没有 官方 Nginx 模 块 
使 用 ， 因 为 它 限 制 过 多 且 post 成 员 过 于 灵活 ， 一 般 完 全 可 以 


init_main_conf 这 样 的 方法 统一 处 理解 析 完 的 配置 项 。 


4.2.3 ”使 用 14 种 预 设 方 法 解析 配置 项 


本 节 将 以 举例 的 方式 说 明 如 何 使 用 这 14 种 Nginx 的 预 设 配置 项 解析 
方法 来 处 理 我 们 感 兴趣 的 配置 项 。 下 面 仍然 以 4.2.1 市 生成 的 配置 项 结构 
体 ngx_http_mytest_conf_t 为 例 进行 说 明 ， 其 中 会 尽量 把 type 成 员 的 多 种 
用 法 都 涵 兰 到 。 


(1) ngx_conf set flag_ slot 


假设 我 们 希望 在 nginx.conf 中 有 一 个 配置 项 的 名 称 为 test_flag， 它 的 
后 面 携带 1 个 参数 ， 这 个 参数 的 取 值 必须 是 on 或 者 off。 我 们 将 用 4.2.1 节 
中 生成 的 ngx_http_mytest_conf t 结 构 体 中 的 以 下 成 员 来 保存 : 








ngx_flag_t my_flag; 





先 看 一 下 ngx_flag_t 的 定义 : 





typedef intptr_t ngx_flag_t; 





可 见 ，ngx_flag_t 与 ngx_int_t 整 型 是 相当 的 。 可 以 如 下 设置 
ngx_conf_set_flag_slot 来 帮助 解析 test_flag 参 数 。 





static ngx_command t ngx_http mytest commands[] = { 





{ ngx_string("test_flag"), 
NGX_HTTP_LOC_CONF| NGX_CONF_FLAG, 
ngx_conf_set_flag_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_flag), 
NULL }, 

ngx_null_ command 











}; 





上 上 段 代 人 码 表示 ，test_flag 配 置 只 能 出 现在 location{...} 块 中 (更 多 的 
type 设 置 可 参见 表 4-1) 。 其 中 ，test_flag 配 置 项 的 参数 为 on 时 ， 
ngx_http_mytest_conf t 结 构 体 中 的 my_flag 会 设 为 1， 而 参数 为 off 时 


my_flag 会 设 为 0。 





@ 注意 在 nex_http_mytest_cteate_loc_conf 创 建 结构 体 时 ， 如 果 想 
使 用 ngx_conf_set_flag_slot， 必 须 把 my_flag 初 始 化 为 
NGX_CONF_UNSET 宏 ， 也 就 是 4.2.1 节 中 的 语句 “mycf- 
>test_flae=NGX_CONPF_UNSET;” ， 否则 ngx_conf_set_flag_slot 方 法 在 解 


析 时 会 报 “is duplicate” 错误 。 
(2) ngx_conf set_ str_slot 


假设 我 们 希望 在 nginx.conf 中 有 一 个 配置 项 的 名 称 为 test_str， 其 后 的 
参数 只 能 是 1 个 ， 我 们 将 用 ngx_http_mytest_conf t 结 构 体 中 的 以 下 成 员 
来 保存 它 。 





ngx_str_t my_str; 





可 以 这 么 设置 ngx_conf_set_str_slot 来 实现 test_str 的 解析 ， 如 下 所 


钞 。 





static ngx_command t ngx_http mytest commands[] = { 





{ ngx_string("test_str"), 
NGX_HTTP_MAIN_CONF |NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF| NGX_CONF_TAKE1., 
ngx_conf_set_str_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_ conf_t, my_str), 
NULL }, 
ngx_null command 


}; 














以 上 代码 表示 test_str 可 以 出 现在 http{...}、server{...} 或 者 
location{...} 块 内 ， 它 携带 的 1 个 参数 会 保存 在 my_str 中 。 例 如 ， 有 以 下 
配置 : 





location … 


test_str apple; 





那么 ，my_str 的 值 为 {len=5;data=“apple”;}。 
(3) ngx_conf set_ str_array_slot 


如 采 和 硕 望 在 nginx.conf 中 有 多 个 同名 配置 项 ， 如 名 称 是 
test_str_array， 那 么 每 个 配置 项 后 都 跟着 一 个 字符 串 参 数 。 这 些 同名 配 
置 项 可 能 具有 多 个 不 同 的 参数 值 。 这 时 ， 可 以 使 用 
ngx_conf_set_str_array_slot 预 设 方法 ， 它 将 会 把 所 有 的 参数 值 都 以 


ngx_str_t 的 类 型 放 到 ngx_array_t 队 列 容器 中 ， 如 下 所 示 。 








static ngx_command t ngx_http mytest commands[] = { 


{ ngx_string("test_str_array"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1, 
ngx_conf_set_str_array_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_str_array), 
NULL }, 

ngx_null command 


}; 














在 4.2.1 节 中 己 看 到 my_str_array 是 ngx_array_t* 类 型 的 。ngx_array_t 
数据 结构 的 使 用 方法 与 ngx_list_t 类 似 。 本 章 不 详细 讨论 ngx_array_t 容 
弹 ， 感 兴趣 的 读者 可 以 直接 陶 读 第 6 章 簿 看 ngx_array_t 的 使 用 特点 。 


上 面 代 码 中 的 test_str_array 配 置 项 也 只 能 出 现在 location{...} 块 内 。 
如 果 有 以 下 配置 : 





location … 


test_str_array Content-Length; 
test_str_array Content-Encoding; 


} 














那么 ，my_str_array->nelts 的 值 将 是 2， 表 示 出 现 了 两 个 test_str_array 配 置 
项 。 而 且 ，my_str_array->elts 指 向 ngx_str_t 类 型 组 成 的 数组 ， 这 样 就 可 
以 按 以 下 方式 访问 这 两 个 值 。 





ngx_str_t*pstr=mycf->my_str_array->elts; 





于 是 ，pstr[0] 和 pstr[1] 可 以 取 到 参数 值 ， 分 别 是 
{len=14;data=“Content-Length”;} 和 {len=16;data=“Content-Encoding”;}。 
从 这 里 可 以 看 到 ， 当 处 理 HITTP 头 部 这 样 的 配置 项 时 是 很 适合 使 用 


ngX_conf_set_str_array_slot 预 设 方法 的 。 
(4) ngx_conf set_ keyval_ slot 


ngx_conf_set_keyval_slot 与 ngx_conf_set_str_array_slot 非 常 相 似 ， 唯 
一 的 不 同 点 是 ngx_conf_set_str_array_slot 要 求 同 名 配置 项 后 的 参数 个 数 
是 1， 而 ngx_conf_set_keyval_slot 则 要 求 配置 项 后 的 参数 个 数 是 2， 分 别 
表示 key/value。 如 果 用 ngx_array_t* 类 型 的 my_keyval 变 量 存储 以 
test_keyval 作 为 配置 名 的 参数 ， 则 必须 设置 NGX_CONF _TAKE2， 表 示 
test_keyval 后 跟 两 个 参数 。 例 如 : 








static ngx_command t ngx_http mytest commands[] = { 


{ ngx_string("test_keyval"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE2, 
ngx_conf_set_keyval_ slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_keyval), 
NULL }, 

ngx_null_ command 


}; 














如 果 nginx.conf 中 出 现 以 下 配置 项 : 





location …: 


test_keyval Content -Type image/png; 
test_keyval Content -Type image/gif; 


test_keyval Accept-Encoding gzip; 








那么 ，ngx_array_t* 类 型 的 my_keyval 将 会 有 3 个 成 员 ， 每 个 成 员 的 类 型 
如 下 所 示 。 





typedef struct { 
ngx_str_t key; 
ngx_str_t value; 
} ngx_keyval t; 








因此 ， 通 过 过 历 my_keyval 就 可 以 获取 3 个 成 员 ， 分 别 是 {*Content- 


Type”,“image/png”}、{“Content-Type’”,“image/gif”}、{“Accept- 
Encoding”,“gzip”}。 例 如 ， 取 得 第 1 个 成 员 的 代码 如 下 。 





ngx_keyval _t* pkv = mycf->my_keyval->elts,; 
ngx_log_error(NGX_LOG ALERT, r->connection->log, 909, 
"my_keyval key=%*s,value=%*s,", 
pkv[0].key.len,pkv[0] .key.data, 
pkv[0] .value.1len,pkv[0].value.data); 





对 于 ngx_log_error 日 志 的 用 法 ， 将 会 在 4.4 节 详细 说 明 。 


@ 注意 在 nex_http_mytest_create_loc_conf 创 建 结 构 体 时 ， 如 果 想 
使 用 ngx_conf_set_keyval_slot， 必 须 把 my_keyval 初 始 化 为 NULL 空 指针 ， 
也 就 是 4.2.1 节 中 的 语句 “mycf->my_keyval=NULL;”， 否 则 


ngx_conf set_keyval_slot 在 解析 时 会 报错 。 


(5) ngx_conf set num_slot 


ngx_conf_set_num_slot 处 理 的 配置 项 必须 携带 1 个 参数 ， 这 个 参数 必 
须 是 数字 。 我 们 用 ngx_http_mytest_conf t 结 构 中 的 以 下 成 员 来 存储 这 个 
数字 参数 如 下 所 示 。 





ngx_int_t my_num; 





如 有 果 用 "test_num" 表 示 这 个 配置 项 名 称 ， 那 么 ngx_command_t 可 以 写 
成 如 下 形式 。 





static ngx_command t ngx_http mytest commands[] = { 





{ ngx_string("test_num"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1., 
ngx_conf_set_num_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_num), 
NULL }, 

ngx_null_ command 











了 





如 果 在 nginx.conf 中 有 test_num 10; 配 置 项 ， 那 么 my_num 变 量 就 会 设 
置 为 10。 


@ 注意 在 nex_http_mytest_cteate_loc_conf 创 建 结构 体 时 ， 如 果 想 
使 用 ngx_conf_set_num_slot， 必 须 把 my_num 初 始 化 为 
NGX_CONF_UNSET 宏 ， 也 就 是 4.2.1 节 中 的 语句 “mycf- 
>my_num 一 NGX_CONF_UNSET;”， 否 则 ngx_conf_set_num_slot 在 解析 


时 会 报错 。 


(6) ngx_conf set size_slot 


如 果 和 希望 配置 项 表达 的 含义 是 空间 大 小 ， 那 么 用 
ngx_conf_set_size_slot 来 解析 配置 项 是 非常 合适 的 ， 因 为 
ngx_conf_set_size_slot 允 许配 置 项 的 参数 后 有 单位 ， 例 如 ，k 或 者 K 表 示 
Kilobyte，m 或 者 M 表 示 Megabyte。 用 ngx_http_mytest_conf t 结 构 中 的 
size_t my_size; 来 存储 参数 ， 解 析 后 的 my_size 表 示 的 单位 是 字 节 。 例 
如 : 





static ngx_command t ngx_http mytest commands[] = { 





{ ngx_string("test_size"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1., 
ngx_conf_set_size_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_size), 
NULL }, 

ngx_null_ command 


}; 














如 果 在 nginx.conf 中 配置 了 test_size 10k;， 那 么 my_size 将 会 设置 为 
10240。 如 果 配 置 为 test_size 10m;， 则 my_size 会 设置 为 10485760。 





ngx_conf set_size_slot 只 人 允许 配置 项 后 的 参数 携带 单位 k 或 者 K、m 
或 者 M， 不 人 允许 有 g 或 者 G 的 出 现 ， 这 与 ngx_conf set_off _ slot 是 不 同 的 。 


@ 注意 在 nex_http_mytest_cteate_loc_conf 创 建 结构 体 时 ， 如 果 想 
使 用 ngx_conf_set_size_slot， 必 须 把 my_size 初 始 化 为 
NGX_CONF_UNSET_SIZE 宏 ， 也 就 是 4.2.1 节 中 的 语句 “mycf- 
>my_size=NGX_CONFP_UNSET_SIZE;”， 否 则 ngx_conf_set_size_slot 在 
解析 时 会 报错 。 


(7) ngx_conf set_off slot 


如 果 和 希望 配置 项 表达 的 含义 是 空间 的 偏 移 位 置 ， 那 么 可 以 使 用 
ngx_conf set_off_ slot 预 设 方法 。 事 实 上 ，ngx_conf set_off _ slot 与 
ngx_conf_set_size_slot 是 非常 相似 的 ， 最 大 的 区 别 是 
ngx_conf_set_off_slot 文 持 的 参数 单位 还 要 多 1 个 g 或 者 G， 表 示 
Gigabyte。 用 ngx_http_mytest_conf t 结 构 中 的 off_t my_off; 来 存储 参数 ， 
解析 后 的 my_off 表 示 的 偏 移 量 单位 是 字 节 。 例 如 : 











static ngx_command t ngx_http mytest commands[] = { 





{ ngx_string("test_off"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1， 
ngx_conf_set_off_slot, NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest conf_t, my_off), 
NULL }, 

ngx_null_ command 











了 





如 果 在 nginx.conf 中 配置 了 test_off 1g;， 那 么 my_off 将 会 设置 为 
1073741824。 当 它 的 单位 为 k、K、m、M 时 ， 其 意义 与 


ngx_conf_set_size_slot 相 同 。 


er 注意 在 nex_http_mytest_cteate_loc_conf 创 建 结构 体 时 ， 如 果 想 
使 用 ngx_conf_set_off_slot， 必 须 把 my_off 初 始 化 为 NGX_CONF_UNSET 
宏 ， 也 就 是 4.2.1 节 中 的 语句 “mycf->my_off=NGX_CONF_UNSET;”,， 


否则 ngx_conf_set_off_slot 在 解析 时 会 报错 。 


(8) ngx_conf set_msec slot 


如 果 和 希望 配置 项 表达 的 含义 是 时 间 长 得， 那么 用 
ngx_conf set_msec_slot 来 解析 配置 项 是 非常 合适 的 ， 因 为 它 文 持 非 常 多 
的 时 间 单 位 。 


用 ngx_http_mytest_conf t 结 构 中 的 ngx_msec_t my_msec; 来 存储 参 
数 ， 解 析 后 的 my_msec 表 示 的 时 间 单 位 是 之 秒 。 事 实 上 ，ngx_msec t 是 


一 个 无 符号 整 型 





typedef ngx_uint t ngx_rbtree key_t; 
typedef ngx_rbtree key_t ngx_msec_t; 








ngx_conf_set_msec_slot 解 析 的 配置 项 也 只 能 携带 1 个 参数 。 例 如 : 





static ngx_command t ngx_http mytest commands[] = { 





{ ngx_string("test_msec"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1., 
ngx_conf_set_msec_slot, NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_msec), 
NULL }, 

ngx_null_command 


了 














如 果 在 nginx.conf 中 配置 了 test_msec 1d;， 那 么 my_msec 会 设置 为 1 天 
之 内 的 毫秒 数 ， 也 就 是 86400000。 


@ 注意 在 nex_http_mytest_cteate_loc_conf 创 建 结构 体 时 ， 如 果 想 
使 用 ngx_conf _set_msec_slot， 那 么 必须 把 my_msec 初 始 化 为 
NGX_CONF_UNSET_MSEC 宏 ， 也 就 是 4.2.1 节 中 的 语句 “mycf- 


>my_msec=NGX_CONF_UNSET_ MSEC;” ， 否 则 ngx_conf_ set_msec_slot 


在 解析 时 会 报错 。 
(9) ngx_conf set sec slot 


ngx_conf_set_sec_slot 与 ngx_conf_set_msec_slot 非 常 相似 ， 只 是 
ngx_conf_set_sec_slot 在 用 ngx_http_mytest_conf _t 结 构 体 中 的 time_t 
my_sec; 来 存储 参数 时 ， 解 析 后 的 my_sec 表 示 的 时 间 单 位 是 秒 ， 而 


ngxX_conf _ set _msec_slot 为 蝶 秒 。 





static ngx_command t ngx_http_mytest_commands[] = { 





{ ngx_string("test_sec"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1., 
ngx_conf_set_sec_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_ conf_t, my_sec), 
NULL }, 

ngx_null_ command 


}; 














如 果 在 nginx.conf 中 配置 了 test_sec 1d;， 那 么 my_sec 会 设置 为 1 天 之 
内 的 秒 数 ， 也 就 是 86400。 


er 注意 在 nex_http_mytest_cteate_loc_conf 创 建 结构 体 时 ， 如 果 想 
使 用 npgx_conf _set_sec_slot， 那 么 必须 把 my_sec 初 始 化 为 
NGX_CONF_UNSET 宏 ， 也 就 是 4.2.1 节 中 的 语句 “mycf- 
>my_sec=NGX_CONF_UNSET;” ， 否 则 ngx_conf set_sec_slot 在 解析 时 
会 报错 。 


(10) ngx_conf set_bufs slot 


Nginx 中 许多 特有 的 数据 结构 都 会 用 到 两 个 概念 : 单个 ngx_buf t 组 
存 区 的 空间 大 小 和 人 允许 的 缓存 区 个 数 。ngx_conf _set_bufs_slot 就 是 用 于 
设置 它 的 ， 它 要 求 配 置 项 后 必须 携带 两 个 参数 ， 第 1 个 参数 是 数字 ， 通 
常会 用 来 表示 缓存 区 的 个 数 ， 第 2 个 参数 表示 单个 缓存 区 的 空间 大 小 ， 
它 像 ngx_conf_set_size_slot 中 的 参数 单位 一 样 ， 可 以 不 携带 单位 ， 也 可 
以 使 用 k 或 者 K、m 或 者 M 作 为 单位 ， 如 “gzip_buffers 48k;”。 我 们 用 
ngx_http_mytest_conf t 结 构 中 的 ngx_bufs_t my_bufs; 来 存储 参数 ， 








ngx_bufs_t (12.1.3 节 ngx_http_upstream_conf t 结 构 体 中 的 bufs 成 员 就 是 
应 用 ngx_bufs_t 配 置 的 一 个 非常 好 的 例子 ) 的 定义 很 简单 ， 如 下 所 示 。 





typedef struct { 
ngx_int_t num; 
size_t size; 

} ngx_bufs_t; 





ngx_conf_set_bufs_slot 解 析 后 会 把 配置 项 后 的 两 个 参数 转化 成 
ngx_bufs_t 结 构 下 的 两 个 成 员 num 和 和 size， 其 中 size 以 字 节 为 单位 。 例 
如 : 





static ngx_command t ngx_http mytest commands[] = { 





{ ngx_string("test_bufs"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE2, 
ngx_conf_set_bufs_slot, NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_bufs), 
NULL }, 

ngx_null command 


}; 














如 果 在 nginx.conf 中 配置 为 test_bufs 41k;， 那 么 my_bufs 会 设置 为 


{4,1024}。 
(11) ngx_conf set _ enum slot 


ngx_conf_set_enum_slot 表 示 枚 举 配 置 项 ， 也 就 是 说 ，Nginx 模 块 代 
码 中 将 会 指定 配置 项 的 参数 值 只 能 是 已 经 定义 好 的 ngx_conf_enum _t 数 
组 中 name 字 符 串 中 的 一 个 。 先 看 看 ngx_conf_enum_t 的 定义 如 下 所 示 。 





typedef struct { 
ngx_str_t name; 
ngx_uint_t value,; 
} ngx_conf_enum_t; 








其 中 ，name 表 示 配 置 项 后 的 参数 只 能 与 name 指 问 的 字符 串 相 等 ， 
而 Value 表 示 如 果 参 数 中 出 现 了 name，ngx_conf_set_enum_slot 方 法 将 会 
把 对 应 的 value 设 置 到 存储 的 变量 中 。 例 如 : 





static ngx_conf_enum t test enums[] = { 
{ ngx_string("apple"), 1 }, 
{ ngx_string("banana"), 
{ ngx_string("orange"), 
{ ngx_null_string, © } 
}; 


23, 
33, 





上 面 这 个 例子 表示 ， 配 置 项 中 的 参数 必须 是 apple、banana、orange 
其 中 之 一 。 注 意 ， 必 须 以 ngx_null_string 结 尾 。 需 要 用 ngx_uint t 来 存储 
解析 后 的 参数 ， 在 4.2.1 节 中 是 用 ngx_http_mytest_conf _t 中 的 “ngx_uint_t 
my_enum_seq;” 来 存储 解析 后 的 枚 举 参 数 的 。 在 设置 ngx_command_t 
时 ， 需 要 把 上 面 例子 中 定义 的 test_enums 数 组 传 给 post 指 针 ， 如 下 所 示 。 


EE | 





static ngx_command t ngx_http mytest commands[] = { 


{ ngx_string("test_enum"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1., 
ngx_conf_set_enum_ slot, NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_enum seq), 
test_enums }, 

ngx_null command 














这 样 ， 如 果 在 nginx.conf 中 出 现 了 配置 项 test_enum banana;， 
my_enum_sedq 的 值 是 2。 如 果 配 置 项 test_enum 出 现 了 除 apple、banana、 
orange 之 外 的 值 ，Nginx 将 会 报 “invalid value” 错 误 。 


(12) 


ngx_conf set_bitmask slot(ngx_conf t*cf,ngx_command_t*cmd,void*conf); 


ngx_conf_set_bitmask_slot 与 ngx_conf_set_enum_slot 也 是 非常 相似 
的 ， 配 置 项 的 参数 都 必须 是 枚 举 成 员 ， 唯 一 的 差别 在 于 效率 方面 ， 
ngX_conf _set_enum_slot 中 枚 举 成 员 的 对 应 值 是 整 型 ， 表 示 序 列 号 ， 它 的 
取 值 范围 是 整 型 的 范围 ， 而 ngx_conf_set_bitmask_slot 中 枚 举 成 员 的 对 应 
值 虽然 也 是 整 型 ， 但 可 以 按 位 比较 ， 它 的 效率 要 高 得 多 。 也 束 是 说 ， 整 
型 是 4 字 节 (32 位》 的 话 ， 在 这 个 枚 举 配 置 项 中 最 多 只 能 有 32 项 。 














由 于 ngx_conf_set_bitmask_slot 与 ngx_conf_set_enum_slot 这 两 个 预 设 
解析 方法 在 名 称 上 的 差别 ， 用 来 表示 配置 项 参数 的 枚 举 取 值 结构 体 也 由 
ngx_conf_enum_t 变 成 了 ngx_conf_bitmask_t， 但 它们 并 没有 区 别 。 





typedef struct { 
ngx_str_t name; 


ngx_uint_t mask 
} ngx_conf_bitmask_t; 





下 面 以 定义 test_bitmasks 数 组 为 例 来 进行 说 明 。 





static ngx_conf_bitmask_t test bitmasks[] = { 
{ ngx_string("good"), Ox0002 }, 
{ ngx_string("better"), Ox0004 }, 
{ ngx_string("best"), Ox0008 }, 
{ ngx_null_string, © } 
}; 





如 果 配 置 项 名 称 定义 为 test_bitmask， 在 nginx.conf 文 件 中 
test_bitmask 配 置 项 后 的 参数 只 能 是 good、better、best 这 3 个 值 之 一 。 我 
们 用 ngx_http_mytest_conf t 中 的 以 下 成 员 : 





ngx_uint_t my_bitmask; 





来 存储 test_bitmask 的 参数 ， 如 下 所 示 。 





static ngx_command t ngx_http mytest commands[] = { 





{ ngx_string("test_bitmask"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1., 
ngx_conf_set_bitmask_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_bitmask), 
test_bitmasks }, 

ngx_null command 








}; 





如 果 在 nginx.conf 中 出 现 配置 项 test_bitmask best;， 那 么 my_bitmask 
的 值 是 0x8。 


(13) ngx_conf set_access slot 


ngx_conf set_access_slot 用 于 设置 读 / 写 权限 ， 配 置 项 后 可 以 携带 
1~3 个 参数 ， 因 此 ， 在 ngx_command_t 中 的 type 成 员 要 包含 
NGX_CONF_TAKE123。 参 数 的 取 值 可 参见 表 4-2。 这 里 用 
ngx_http_mytest_conf t 结 构 中 的 “ngx_uint_t my_access;” 来 存储 配置 
项 “test_access” 后 的 参数 值 ， 如 下 所 示 。 





static ngx_command t ngx_http mytest commands[] = { 





{ ngx_string("test_access"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE123, 
ngx_conf_set_access_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_access), 
NULL }, 

ngx_null_ command 


}; 














这 样 ，ngx_conf set_access_slot 驶 可 以 解析 读 / 写 权限 的 配置 项 了 。 
例如 ， 当 nginx.conf 中 出 现 配 置 项 test_access user:rw group:rw all:r; 时 ， 


my_access 的 值 将 是 436。 


er 注意 在 nex_http_mytest_cteate_loc_conf 创 建 结构 体 时 ， 如 果 想 
使 用 ngx_conf_set_access_slot， 那 么 必须 把 my_access 初 始 化 为 
NGX_CONF_UNSET_UINT 宏 ， 也 就 是 4.2.1 节 中 的 语句 “mycf- 
>my_access=NGX_CONF_UNSET_UINT;”， 否 则 


ngx_conf set_access_slot 解 析 时 会 报错 。 


(14) ngx_conf set_path slot 


ngx_conf set_path_slot 可 以 携 市 1~4 个 参数 ， 其 中 第 1 个 参数 必须 是 
路 径 ， 第 2~4 个 参数 必须 是 整数 《〈 大 部 分 情形 下 可 以 不 使 用 ) ， 可 以 参 
见 2.4.3 节 中 client_body_temp_path 配 置 项 的 用 法 ，client_body_temp_path 
配置 项 就 是 用 ngx_conf_set_path_slot 预 设 方法 来 解析 参数 的 。 


ngx_conf_set_path_slot 会 把 配置 项 中 的 路 径 参 数 转化 为 ngx_path_t 结 
构 ， 看 一 下 ngx_path_t 的 定义 。 





typedef struct { 
ngx_str_t name; 
size_t len; 
size_t level[3]; 
ngx_path_manager_pt manager; 
ngx_path_loader_pt loader; 
void *data; 
u_char *conf_file; 
ngx_uint_t line; 

} ngx_path_t; 





其 中 ，name 成 员 存 储 着 字符 串 形式 的 路 径 ， 而 level 数 组 束 会 存储 大 
第 >、 第 3、 第 4 个 参数 (如 果 存 在 的 话 ) 。 这 里 用 
ngx_http_mytest_conf t 结 构 中 的 “ngx_path_t*my_path;” 来 存储 配置 
项 “test_path” 后 的 参数 值 。 











static ngx_command t ngx_http mytest commands[] = { 





{ ngx_string("test_path"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1234, 
ngx_conf_set_path_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_path), 
NULL }, 

ngx_null command 











}; 


ey 


如 果 nginx.conf 中 存在 配置 项 test_path/usr/local/nginx/123;，my_path 
指 癌 的 ngx_path_t 结 构 中 ，name 的 内 容 是 /usr/local/nginx/， 而 level[0] 为 
1，level[1] 为 2，level[2] 为 3。 如 果 配 置 项 是 “test_path/usr/local/nginx/;”， 
那么 level 数 组 的 3 个 成 员 都 是 0。 


4.2.4 目 定 义 配置 项 处 理 方 法 


除了 使 用 Nginx 已 经 实现 的 14 个 通用 配置 项 处 理 方 法 外 ， 还 可 以 自 
己 编 写 专用 的 配置 项 处 理 方法 。 事 实 上 ，3.5 节 中 的 ngx_http_mytest 残 是 
自 定 义 的 处 理 mytest 配 置 项 的 方法 ， 只 是 没有 去 处 理 配置 项 的 参数 而 
已 。 本 贡 举 例 说 明 如 何 编写 方法 来 解析 配置 项 。 


假设 我 们 要 处 理 的 配置 项 名 称 是 test_config， 它 接收 1 个 或 者 2 个 参 
数 ， 且 第 1 个 参数 类 型 是 字符 串 ， 第 2 个 参数 必须 是 整 型 。 定 义 结构 体 来 


存储 这 两 个 参数 ， 如 下 所 示 。 





typedef struct { 
ngx_str_t my_config_str; 
ngx_int_t my_config_num; 
} ngx_http_mytest_conf_t; 














其 中 ，my_config_str 存 储 第 1 个 字符 串 参 数 ，my_config_num 存 储 第 


2 个 数字 参数 。 


首先 ， 我 们 按照 4.2.2 节 ngx_command_s 中 的 set 方 法 指针 格式 来 定义 


这 个 配置 项 处 理 方法 ， 如 下 所 示 。 





static char* ngx_conf_set myconfig(ngx_conf_t *cf, ngx_command t *cmd, void *conf ) ， 





接 下 来 定义 ngx_command_t 结 构 体 ， 如 下 所 示 。 








static ngx_command t ngx_http mytest commands[] = { 


{ ngx_string("test_myconfig"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE12, 
ngx_conf_set_myconfig, 
NGX_HTTP_LOC_CONF_OFFSET, 

09, 

NULL }, 

ngx_null_ command 





}; 





这 样 ，test_myconfig 后 就 必须 跟着 1 个 或 者 2 个 参数 了 。 现 在 开始 实 
现 ngx_conf_set_myconfig 处 理 方法 ， 如 下 所 示 。 





static char* ngx_conf_set myconfig(ngx_conf_t *cf, ngx_command t *cmd, void *conf) 


/* 注 意 ， 参 数 


conf 就 是 


HTTP 框 架 传 给 用 户 的 在 


ngx_http_mytest_create_loc_conf 回 调 方 法 中 分 配 的 结构 体 





ngx_http_mytest_conf_t*/ 
ngx_http_mytest _ conf_t *mycf = conf; 
/* cf->args 是 








人 


ngx_array_t 队 列 ， 它 的 成 员 都 是 


ngx_str_t 结 构 。 我 们 用 


Value 指 向 


ngx_array_t 的 


elts 内 容 ， 其 中 


Value[1] 就 是 第 


1 个 参数 ， 同 理 ， 


Value[2] 是 第 


2 个 参数 


*/ 
ngx_str_t* value = cf->args->elts,; 
// ngx_array_t 的 


nelts 表 示 参 数 的 个 数 


if (cf->args->nelts > 1) 


// 直接 赋值 即 可 ， 


ngx_Str_ t 结 构 只 是 指针 的 传递 


mycf->my_config_str = Value[1]， 


if (cf->args->nelts > 2) 


{ 
// 将 字符 串 形 式 的 第 
2 个 参数 转 为 整 型 


mycf->my_config_num = ngx_atoi(value[2].data, value[2].1en); 
/* 如 果 字 符 串 转化 整 型 失败 ， 将 报 “ 


invalid number” 错 误 ， 


Nginx 启 动 失败 


*/ 
If (mycf->my_config_num == NGX_ERROR) { 
return "invalid number",; 
} 
} 
// 返回 成 功 


return NGX_CONF_OK， 





假设 nginx.conf 中 出 现 test_myconfig jordan 23; 配 置 项 ， 那 么 


my_config_ str 的 值 是 jordan， 而 my_config_num 的 值 是 23。 


4.2.5 合并 配置 项 


回顾 一 下 4.1 节 中 的 例子 ， 一 个 test_str 配 置 同时 在 http{.…}、 
server{...}、location/arl1{...} 中 出 现时 ， 到 底 以 哪 一 个 为 准 ?本 节 将 讨论 
如 何 合 并 不 同 配置 块 间 的 同名 配置 项 ， 首 先 回 顾 一 下 4.2.1 节 中 
ngx_http_module_t 的 结构 。 





typedef struct { 


void *(*create loc conf)(ngx_conf_t *cf); 
char *(*merge_ loc conf)(ngx_conf_t *cf, void *prev, void *conf ) ， 


} ngx_http_module_t; 


| ———= | 


上 面 这 段 代码 定义 了 create_loc_conf 方 法 ， 意 味 着 HTTP 框 架 会 建立 
loc 级 别 的 配置 。 什 么 意思 呢 ? 就 是 说 ， 如 果 没 有 实现 merge_loc_conf 方 
法 ， 也 就 是 在 构造 ngx_http_module_t 时 将 merge_loc_conf 设 为 NULL 了， 
那么 在 4.1 节 的 例子 中 server 块 或 者 http 块 内 出 现 的 配置 项 都 不 会 生效 。 
如 果 我 们 希望 在 server 块 或 者 http 块 内 的 配置 项 也 生效 ， 那 么 可 以 通过 
merge_loc_conf 方 法 来 实现 。merge_loc_conf 会 把 所 属 父 配置 块 的 配置 项 
与 子 配置 块 的 同名 配置 项 合并 ， 当 然 ， 如 何 合并 取决 于 有 具体 的 


merge_loc_conf 实 现 。 





merge_loc_conf 有 3 个 参数 ， 第 1 个 参数 仍然 是 ngx_conf_t*cf， 提 供 
一 些 基 本 的 数据 结构 ， 如 内 存 池 、 日 志 等 。 我 们 需要 关注 的 是 第 >、 第 3 
个 参数 ， 其 中 第 2 个 参数 void*prev 是 指 解析 父 配置 块 时 生成 的 结构 体 ， 
而 第 3 个 参数 void*conf 则 指出 的 是 保存 子 配 置 块 的 结构 体 。 


仍 以 4.1 市 的 例子 为 例 ， 来 看 看 如 何 合并 同时 出 现 了 6 次 的 test_str 配 
项 ， 如 下 所 示 。 





static char * 
ngx_http_mytest_merge_loc conf(ngx_conf_t *cf, void *parent, void *child) 





ngx_http_mytest_conf_t *prev = (ngx_http_mytest_conf_t *)parent,; 
ngx_http_mytest_conf_t *conf = (ngx_http_mytest conf_t *)child; 
ngx_conf_merge_str_value(conf->my_str, 

prev->my_str, "defaultstr"); 
return NGX_CONF_OK,; 




















可 以 看 到 ， 只 需要 按照 自己 的 需求 将 父 配 置 块 的 值 赋予 子 配 置 块 即 


可 ， 这 时 表示 父 配置 块 优先 级 更 高 ， 反 过 来 也 是 可 以 的 ， 表 示 子 配置 块 
的 优先 级 更 高 。 例 如 ， 在 解析 server{.…} 块 时 《〈《 传 入 的 child 参 数 就 是 当前 
server 块 的 ngx_http_mytest_conf t 结 构 ) ， 父 配置 块 《〈 也 就 是 传 入 的 
parent 参 数 ) 就 是 http{..….} 块 ; 解析 location{.…} 块 时 父 配置 块 就 是 
server{...} 块 。 


如 何 处 理 父 、 子 配置 块 下 的 同名 配置 项 ， 每 个 HTTP 模 块 都 可 以 自 
由 选择 。 例 如 ， 可 以 简单 地 以 父 配置 替 换 子 配置 ， 或 者 将 两 种 不 同 级 别 
的 配置 做 完 运 算 后 再 覆盖 等 。 上 面 的 例子 对 不 同 级 别 下 的 test_str 配 置 项 
的 处 理 是 最 简单 的 ， 下 面 我 们 使 用 Nginx 预 置 的 
ngx_conf_merge_str_value 宏 来 合并 子 配置 块 中 ngx_str_t 类 型 的 my_str 成 
员 ， 看 看 ngx_conf_merge_str_value 到 底 做 了 哪些 事情 。 














#define ngx_conf_merge_str_value(conf, prev, default) 和 
// 当前 配置 块 中 是 否 已 经 解析 到 





test_str 配 置 项 


if (conf.data == NULL){ \ 
// 父 配置 块 中 是 否 已 经 解析 到 


test_str 配 置 项 


if (prev.data) { \ 
// 将 父 配置 块 中 的 


test_Sstr 参 数值 直接 覆盖 当前 配置 块 的 


test_str 
conf.len = prev.1len; \ 
conf.data = prev.data; \ 


} else { \ 
A/* 如 果 父 配置 块 和 子 配 置 块 都 没有 解析 到 


test_str, 以 


default 参 数 作 为 默认 值 传 给 当前 配置 块 的 


test_str*/ 
conf.len = sizeof(default) - 1; \ 
conf.data = (u_char *) default; \ 
} \ 
} 








事实 上 ，Nginx 预 设 的 配置 项 合并 方法 有 10 个 ， 


它们 的 行为 与 上 述 


的 IO 似 的 。 参 见 表 4-5 中 Nginx 已 经 实现 好 的 
10 个 简单 的 配置 项 合并 宏 ， 它 们 的 参数 类 型 与 ngx_conf_merge_str_value 


一 致 ， 而 且 除 了 ngx_conf_merge_bufs_value 外 ， 
分 别 表 示 父 配置 块 参 数 、 子 配置 块 参数 、 默 认 值 。 


表 4-5 Nginx 预 设 的 10 种 配置 项 合 


配置 项 合并 宏 意 义 


合并 可 以 使 用 等 号 (=) 直接 赋值 的 变量 ， 
ngx conf merge value 分 配方 法 中 初始 化 为 NGX_CONF_UNSET， 


conf mersge_value 合并 安 


合并 指针 类 型 的 变量 ， 并 且 该 


它们 都 将 接收 3 个 参数 ， 


2 


并 安 


并 且 该 变量 在 create loc_conf 等 
这 样 类 型 的 成 员 可 以 使 用 ngx_ 


变量 在 create_loc_conf 等 分 配方 法 中 初始 化 


ngx_conf Imerge_ptr_value 为 NGX_ CONEF _ UNSET _ PTR， 这 样 类 型 的 成 员 可 以 使 用 > DE 
value 合并 宏 
合并 整数 类 型 的 变量 ， 并 且 该 变量 在 create_loc_conf 等 分 配方 法 中 初始 化 为 
ngx conf merge uint value NGX_CONF_UNSET_UINT， 这 样 类 型 的 成 员 可 以 使 用 ngx_conf merge_uint 





value 合并 宏 


合并 表示 毫秒 的 ngx_msec t 类 型 的 变量 ， 





放量 该 变量 在 create_loc_conf 等 


ngx_conf merge msec value 分 配方 法 中 初始 化 为 NGX_CONF_UNSET_MSEC， 这 样 类 型 的 成 员 可 以 使 用 


ngx_conf merge_msec_value 合并 安 





配置 项 合并 宏 


ngx conf merge sec value 


ngx conf merge size value 


ngx conf merge off value 


ngx conf merge str value 


ngx conf merge bufs value 





ngx conf merge bitmask value 





意 义 

合并 表示 秒 的 time_t 类 型 的 变量 ， 并 且 该 变量 在 create_loc_conf 等 分 配方 法 
中 初始 化 为 NGX_CONF_UNSET， 这 样 类 型 的 成 员 可 以 使 用 ngx_conf merge _ 
sec_value 合并 安 

合并 size t 等 表示 空间 长 度 的 变量 ， 并 且 该 变量 在 create loc_conf 等 分 配 
方法 中 初始 化 为 NGX_CONEF UNSET _ SIZE， 这 样 类 型 的 成 员 可 以 使 用 ngx 
conf merge_size_value 合并 宏 

合并 off t 等 表示 偏 移 量 的 变量 ， 并 且 该 变量 在 create loc_conf 等 分 配方 法 
中 初始 化 为 NGX_CONF_UNSET， 这 样 类 型 的 成 员 可 以 使 用 ngx_conf merge_ 
off value 合并 安 


ngx_str t 类 型 的 成 员 可 以 使 用 ngx_conf_ merge_str_value 合并 ， 这 时 传人 的 
default 参数 必须 是 一 个 char* 字符 串 

ngx_bufs t 类 型 的 成 员 可 以 使 用 ngx_conf_merge_bufs_value 合并 宏 ， 这 时 传 
和 的 default 参数 是 两 个 ， 因 为 ngx_bufs t 类 型 有 两 个 成 员 ， 所 以 需要 传人 两 
个 默认 值 

以 二 进 制 位 来 表示 标志 位 的 整 型 成 员 ， 可 以 使 用 ngx_conf merge_bitmask_ 
value 合并 安 





在 4.3.3 节 中 我 们 会 看 到 HTTP 框 架 在 什么 时 候 会 调用 各 模块 的 
merge_loc_conf 方 法 或 者 merge_srv_conf 方 法 。 


4.3 _ HTTP 配置 模型 


上 文中 我 们 了 解 了 如 何 使 用 Nginx 提 供 的 预 设 解析 方法 来 处 理 自己 
感 兴趣 的 配置 项 ， 由 于 http 配 置 项 设计 得 有 些 复 杂 ， 为 了 更 清晰 地 使 用 
好 ngx_command t 结 构 体 处 理 http 配 置 项 ， 本 节 将 简单 讨论 HTTP 配置 模 
型 是 怎样 实现 的 ， 在 第 10 章 我 们 会 从 HTTP 框 架 的 角度 谈 谈 它 是 怎么 管 
理 每 一 个 HTTP 模 块 的 配置 结构 体 的 。 


当 Nginx 检 测 到 http{...} 这 个 关键 配置 项 时 ，HTTP 配 置 模型 就 启动 
了 ， 这 时 会 首先 建立 1 个 ngx_http_conf_ctx_t 结 构 。 下 面 看 一 下 


ngx_http_conf_ctx_t 的 定义 。 





typedef struct { 
/* 指 针 数 组 ， 数 组 中 的 每 个 元 素 指向 所 有 


HTTP 模 块 


create_main_conf 方 法 产生 的 结构 体 


*/ 
void **main_conf; 
/* 指 针 数 组 ， 数 组 中 的 每 个 元 素 指 向 所 有 


HTTP 模 块 


create_srv_conf 方 法 产生 的 结构 体 


*/ 
void **srv_conf; 
/* 指 针 数 组 ， 数 组 中 的 每 个 元 素 指 向 所 有 


HTTP 模 块 


create_1oc_conf 方 法 产生 的 结构 体 


*/ 
void **]loc_conf; 
} ngx_http_conf_ctx_t; 








这 时 ，HTTP 框 架 会 为 所 有 的 HTTP 模 块 建立 3 个 数组 ， 分 别 存放 所 
有 HTTP 模 块 的 create_main_conf、create_SsrV_conf、create_loc_conf 方 法 
返回 的 地 址 指针 就 像 本 章 的 例子 中 mytest 模 块 在 create_loc_conf 中 生成 
了 ngx_http_mytest_conf t 结 构 ， 并 在 create_loc_conf 方 法 返回 时 将 指针 传 
递 给 HTTP 框 架 ) 。 当 然 ， 如 果 HTTP 模 块 对 于 配置 项 不 感 兴 趣 ， 它 没有 
实现 create_main_conf、create_srv_conf、create_loc_conf 等 方法 ， 那 么 数 
组 中 相应 位 置 存储 的 指针 是 NULL。ngx_http_conf_ctx_t 的 3 个 成 员 
main_conf、srv_conf、loc_conf 分 别 指向 这 3 个 数组 。 下 面 看 一 段 简 化 的 
代码 ， 了 解 如 何 设置 create_loc_conf 返 回 的 地 址 。 





ngx_http_conf_ctx_t *ctx; 
// HTTP 框 架 生成 了 





1 个 


ngx_http_conf_ctx_t 结 构 





ctx = ngx_pcalloc(cf->pool, sizeof(ngx_http_conf_ctx_t)); 
if (ctx == NULL) { 
return NGX_CONF_ERROR, 





} 
// 生成 


1 个 数组 存储 所 有 的 


HTTP 模 块 


Create_1oc_conf 方 法 返回 的 地 址 


ctx->loc_conf = ngx_pcalloc(cf->pool, sizeof(void *) * ngx_http_max_module); 
if (ctx->loc conf == NULL) { 
return NGX_CONF_ERROR, 


} 
// 遍历 所 有 的 


HTTP 模 块 


for (m= 0; ngx modules[m]; m++) { 
if (ngx_modules[m]->type != NGX_HTTP_MODULE) { 
continue; 


module = ngx_modules[m]->ctx; 
mi = ngx_modules[m]->ctx_index; 
/* 如 果 这 个 


HTTP 模 块 实现 了 
create_loc_conf， 就 调用 它 ， 并 把 返回 的 地 址 存储 到 
Joc_conf 中 


*/ 
If (module->create loc conf) { 
ctx->loc_conf[mi] = module->create loc_ conf(cf); 
If (ctx->loc_ conf[mi] == NULL) 区 
return NGX_CONF_ERROR ， 
} 





这 样 ， 在 http{..….} 块 中 就 通过 1 个 ngx_http_conf_ctx_t 结 构 保 存 了 所 有 
HTTP 模 块 的 配置 数据 结构 的 入 口 。 以 后 遇 到 任何 server{...} 块 或 者 
location{..} 块 时 ， 也 会 建立 ngx_http_conf_ctx_t 结 构 ， 生 成 同样 的 数组 
来 保存 所 有 HTTP 模 块 通过 create_srv_conf、create_loc_conf 等 方法 返回 
的 指针 地 址 。ngx_http_conf_ctx_t 是 了 解 http 配 置 块 的 基础 ， 下 面 我 们 来 


看 看 具体 的 解析 流程 。 


4.3.1 解析 HTTP 配 置 的 流程 





图 4-1 是 HITP 框 架 解 析 配 置 项 的 示意 流程 图 〈 图 中 出 现 了 
ngx_http_module 和 ngx_http_core_module 模 块 ， 所 谓 的 HTTP 框架 主要 由 
这 两 个 模块 组 成 ) ， 下 面 解释 图 中 每 个 流程 的 意义 。 


主 循环 | 配置 文件 解析 器 | | ede nt | ome een st ngx_http _core _module | ap eore module _core _module | mess tk | 


1. 解析 配置 文件 1 
| 


| 
1 2. 发现 http 配置 项 
| 


Wi 3 .初始 化 每 一 个 HTTP 模块 


4. 依次 调用 各 模块 的 create _ (main 、srv 、loc ) _conf 


loc ) _conf 


| 
| 
| 
| 
| | 
: | 5 泛 回 分 页 弛 的 内 存 指 对 | 
| he RE 了 
| | 
| | 6. OE | 
| | | 
| | a i | 
| 1< 一 a eh ee a i 
8. 开始 解析 http 块 下 的 配置 项 J ; 
' | | 
| | | 
有 后 ,遍历 所 有 模块 的 所 有 command | 
10. 根据 command 描述 , 回调 相应 的 方法 | 
| | 
| | | | 
1 11. 配置 项 处 理 完毕 “| | 
本 Sh 
La I | I 
12. 发 现 server 配置 项 1 | 
| | 
I 13. 依次 调用 各 模块 的 rreate - (sv 、 
| 
| | | 
| 14. 返回 分 配 好 的 内 存 指 针 
| 上 | 
|。 15. 开始 解析 server 块 下 的 配置 项 ; 
人 
| | | 
| | | | 
| 16. 依 此 类 推 | | 
1 17. server at | | 
A | | 
| 一 2 | 
18. server 人 元 毕 | | 
pe ee tei | 
涟 | | | 
19. http 配置 项 处 理 完 毕 | | 
' | | | 
| | 
人 > 合同 了 同名 配 昌 
| 
21. http 配置 项 处 理 完毕 | | 
| 


| | 
22. 配 置 项 处 理 完 毕 


图 4-1 解析 http 配 置 项 的 示意 流程 图 


1) 图 4-1 中 的 主 循环 是 指 Nginx 进 程 的 主 循环 ， 主 循环 只 有 调用 配 
置 文件 解析 器 才能 解析 nginx.conf 文 件 〈 这 里 的 “ 主 循环 ”是 指 解析 全 部 配 
置 文件 的 循环 代码 ， 图 8-6 的 第 4 步 ， 为 了 便于 理解 ， 可 以 认为 是 Nginx 
框架 代码 在 循环 解析 配置 项 )。 


2) 当 发 现 配 置 文件 中 含有 http{} 关 键 字 时 ，HTTP 框 架 开始 启动 ， 
这 一 过 程 详 见 10.7 节 描述 的 ngx_http_block 方 法 。 





3) HTTP 框 架 会 初始 化 所 有 HTTP 模 块 的 序列 号 ， 并 创建 3 个 数组 用 
于 存储 所 有 HTTP 模 块 的 create_main_conf、create_srv_conf、 
create_loc_conf 方 法 返回 的 指针 地 址 ， 并 把 这 3 个 数组 的 地 址 保存 到 


ngx_http_conf_ctx_t 结 构 中 。 


4) 调用 每 个 HTTP 模块 《当然 也 包括 例子 中 的 mytest 模 块 ) 的 
create_main conf、create_srvy_conf、create_loc_conf 〈 如 果实 现 的 话 ) 方 


Uy 


5) 把 各 HTTP 模 块 上 述 3 个 方法 返回 的 地 址 依次 保存 到 
ngx_http_conf_ctx_t 结 构 体 的 3 个 数组 中 。 


6) 调用 每 个 HTTP 模 块 的 preconfiguration 方 法 (如 果实 现 的 话 ) 。 


7) 注意 ， 如 果 preconfiguration 返 回 失 败 ， 那 么 Nginx 进 程 将 会 停 
I 


8) HTTP 框 架 开始 循环 解析 nginx.conf 文 件 中 http{...} 里 面 的 所 有 配 


置 项 ， 注 意 ， 这 个 过 程 到 第 19 步 才 会 返回 。 





9) 配置 文件 解析 器 在 检测 到 1 个 配置 项 后 ， 会 禹 历 所 有 的 HITP 模 
块 ， 检 查 它 们 的 ngx_command_t 数 组 中 的 name 项 是 否 与 配置 项 名 相同 。 


10) 如 果 找 到 有 1 个 HITP 模 块 〈 如 mytest 模 块 ) 对 这 个 配置 项 感 兴 
趣 〈 如 test_myconfig 配 置 项 ) ， 就 调用 ngx_command t 结 构 中 的 set 方 法 
来 处 理 。 


11) set 方 法 返回 是 否 处 理 成 功 。 如 果 处 理 失 败 ， 那 么 Nginx 进 程 会 


12) 配置 文件 解析 器 继续 检测 配置 项 。 如 果 发 现 server{...} 配 置 项 ， 
就 会 调用 ngx_http_core_module 模 块 来 处 理 。 因 为 ngx_http_core_module 
模块 明确 表示 希望 处 理 server{} 块 下 的 配置 项 。 注 意 ， 这 次 调用 到 第 18 


步 才 会 返回 。 


13) ngx_http_core_module 模 块 在 解析 server{...} 之 前 ， 也 会 如 第 3 步 
一 样 建立 ngx_http_conf_ctx_t 结 构 ， 并 建立 数组 保存 所 有 HTTP 模 块 返回 
的 指针 地 址 。 然 后 ， 它 会 调用 每 个 HTTP 模 块 的 create_srv_conf、 
create_loc_conf 方 法 〈( 如 果实 现 的 话 )。 


14) 将 上 一 步 各 HTTP 模 块 返回 的 指针 地 址 保存 到 


ngx_http_conf_ctx_t 对 应 的 数组 中 。 


15) 开始 调用 配置 文件 解析 器 来 处 理 server{...} 里 面 的 配置 项 ， 注 


意 ， 这 个 过 程 在 第 17 步 返回 。 





16) 继续 重复 第 9 步 的 过 程 ， 遍 历 nginx.conf 中 当前 server{...} 内 的 所 
有 配置 项 。 


17) 配置 文件 解析 器 继续 解析 配置 项 ， 发 现 当 前 server 块 已 经 遍历 
到 尾部 ， 说 明 server 抉 内 的 配置 项 处 理 完 毕 ， 返 回 ngx_http_core_module 
模块 。 


18) http core 模 块 也 处 理 完 server 配 置 项 了 ， 返 回 至 配置 文件 解析 喜 
继续 解析 后 面 的 配置 项 。 


19) 配置 文件 解析 器 继续 解析 配置 项 ， 这 时 发 现 处 理 到 了 http{…} 
的 尾部 ， 返 回 给 HTTP 框 架 继续 处 理 。 








20) 在 第 3 步 和 第 13 步 ， 以 及 我 们 没有 列 出 来 的 某 些 步骤 中 《如 发 
现 其 他 server 块 或 者 location 块 ) ， 都 创建 了 ngx_http_conf_ctx_t 结 构 ， 这 
时 将 开始 调用 merge_srv_conf、merge_loc_conf 等 方法 合并 这 些 不 同 块 
(http、server、location〉 中 每 个 HTTP 模 块 分 配 的 数据 结构 。 


21) HTTP 框 架 处 理 完毕 http 配 置 项 (也 就 是 ngx_command_t 结 构 中 
的 set 回 调 方法 处 理 完毕 ) ， 返 回 给 配置 文件 解析 器 继续 处 理 其 他 


http{.….} 外 的 配置 项 。 


22) 配置 文件 解析 井 处 理 完 所 有 配置 项 后 会 告诉 Nginx 主 循环 配置 
项 解析 完毕 ， 这 时 Nginx 才 会 启动 Web 服 务 器 。 








@ 注意 ”图 4-1 并 没有 列 出 解析 location{...} 块 的 流程 ， 实 际 上 ， 解 
析 ]location 与 解析 server 并 没有 本 质 上 的 区 别 ， 为 了 简化 起 见 ， 没 有 把 它 
画 到 图 中 。 


4.3.2 HTTP 配置 模型 的 内 存 布局 


了 解 内 存 布局 ， 会 帮助 理解 使 用 create_main_conf、 
create_srv_conf、create_loc_conf 等 方法 在 内 存 中 创建 了 多 少 个 存放 配置 
项 的 结构 体 ， 以 及 最 终 处 理 请 求 时 ， 使 用 到 的 是 哪个 结构 体 。 我 们 已 经 
看 到 ，http{} 块 下 有 1 个 ngx_http_conf_ctx_t 结 构 ， 而 每 一 个 server{} 块 下 
也 有 1 个 ngx_http_conf_ctx_t 结 构 ， 它 们 的 关系 如 图 4-2 所 示 。 


图 4-2 插 述 了 http 块 与 系 个 server 块 下 存储 配置 项 参数 的 结构 体 间 的 
关系 。 某 个 server 块 下 ngx_http_conf_ctx_t 结 构 中 的 main_conf 数 组 将 通过 
直接 指向 来 复 用 所 属 的 http 块 下 的 main_conf 数 组 〈 其 实 是 说 server 抉 下 
没有 main 级 别 配 置 ， 这 是 显然 的 ) 。 





可 以 看 到 ，ngx_http_conf_ctx_t 结 构 中 的 main_conf、srv_conf、 


loc_conf 数 组 保存 了 所 有 HTTP 模 块 使 用 create_main_conf、 
create_srv_conf、create_loc_conf 方 法 分 配 的 结构 体 地 址 。 每 个 HTTP 模 
块 都 有 自己 的 序号 ， 如 第 1 个 HTTP 模 块 就 是 ngx_http_core_module 模 
块 。 当 在 http{.…} 内 遍历 到 第 2 个 HTTP 模 块 时 ， 这 个 HTTP 模块 已 经 使 用 
create_main_conf、create_srv_conf、create_loc_conf 方 法 在 内 存 中 创建 了 
3 个 结构 体 ， 并 把 地 址 放 到 了 ngx_http_conf_ctx_t 内 3 个 数组 的 第 2 个 成 员 
中 。 在 解析 server{..….} 块 时 遍历 到 第 2 个 HTTP 模 块 时 ， 除 了 不 调用 
create_main_conf 方 法 外 ， 其 他 完全 与 http{.…} 内 的 处 理 一 致 。 


当 解 析 到 ]ocation{...} 块 时 ， 也 会 生成 1 个 ngx_http_conf_ctx_t 结 构 ， 
其 中 的 3 个 指针 数组 与 server{...}、http{...} 块 内 ngx_http_conf_ctx_t 结 构 
的 关系 如 图 4-3 所 示 。 


从 图 4-3 可 以 看 出 ， 在 解析 location{...} 块 时 只 会 调用 每 个 HITP 模 块 
的 create_loc_conf 方 法 创建 存储 配置 项 参数 的 内 存 ，ngx_http_conf_ctx_t 
结构 的 main_conf 和 srv_conf 都 直接 引用 其 所 属 的 server 块 下 的 
ngx_http_conf_ctx_t 结 构 。 这 也 是 显然 的 ， 因 为 location{...} 块 中 当然 没 
有 main 级 别 和 srv 级 别 的 配置 项 ， 所 以 不 需要 调用 各 个 HTTP 模 块 的 
create_main_conf、create_srv_conf 方 法 生成 结构 体 存放 main、srv 配 置 
项 。 





http 块 下 的 ngx_http _conf _ctx 上 


所 有 HTTP 模 块 cre: 
_main_conf 产 aed 
i 
第 2 个 HTTP 模 块 存 储 ce ed TTP 模 块 create_srvy _conf 产生 的 指针 


FR 


main 级 别 配 置 、 由 


create _main _conf 分 虱 针 1 针 2 | 
和 站 有 


C7 


第 2 个 HTTP 模 块 存 


一 一 
main 级 别 配置 、 由 EE 


create _srv_conf 分 配 


的 结构 体 





第 2 个 HTTP 模 块 存储 
main 级 别 配置 、 由 


create_loc_conf 分 配 


i 





所 有 HTTP 模 块 create_loc _conf 产生 的 指针 


某 个 server 块 下 的 ngx_http _conf _ctx 上 


所 有 HTTP 模块 create _srv_conf 产生 的 指针 


“i 
| 


所 有 HTTP 模 块 create_loc conf 产生 的 指针 
A 


| 









第 2 个 HTTP 模 块 存储 
srv 级 别 配置 、 由 


create __srv_conf 分 配 
的 结构 体 





srv 级 别 配置 、 
create _loc__conf 分 配 
的 结构 体 


图 4-2 http 块 与 Server 块 下 的 ngx_http_conf_ctx_t 所 指向 的 内 存 间 的 关系 


图 4-2 和 图 4-3 说 明了 一 个 事实 : 在 解析 nginx.conf 配 置 文件 时 ， 


解析 到 http{} 块 ， 将 会 调用 所 有 HTTP 模 块 的 create_main_conf、 


create_srv_conf、create_loc_conf 方 法 创建 3 组 结构 体 ， 以 便 存 放 各 个 
HTTP 模 块 感 兴趣 的 main 级 别 配 置 项 ， 在 解析 到 任何 一 个 server{} 块 时 ， 
又 会 调用 所 有 HTTP 模 块 的 create_srv_conf、create_loc_conf 方 法 创建 两 
组 结构 体 ， 以 存放 各 个 HTTP 模 块 感 兴 趣 的 srv 级 别 配 置 项 ， 在 解析 到 任 
何 一 个 location{} 块 时 ， 则 会 调用 所 有 HTTP 模 块 的 create_loc_conf 方 法 创 
建 1 组 结构 体 ， 用 于 存放 各 个 HTTP 模 块 感 兴趣 的 loc 级 别 配置 项 。 


http 块 下 的 ngx_http _conf _ctx _t 












某 server 块 下 的 ngx_http _conf _ctx _t 


该 server 所 属 的 某 个 location 
块 下 的 ngx_http _conf _ctx_t 


所 有 HTTP 模 块 create_loc _conf 产生 的 指针 


ED ED EE 


第 2 个 HTTP 模块 存储 


loc 级 别 配置 、 由 
create _loc _conf 分 配 


的 结构 体 


图 4-3 ”location 块 与 http 块 、server 块 下 分 配 的 内 存 关 系 


这 个 事实 告诉 我 们 ， 在 nginx.conf 配 置 文件 中 http{}、server{}、 
location{} 块 的 总 个 数 有 多 少 ， 我 们 开发 的 HTTP 模 块 中 create_loc_conf 方 
法 (如 果实 现 的 话 〉 就 会 被 调用 多 少 次 ，http{}、server{} 块 的 总 个 数 有 


多 少 ，create_srv_conf 方 法 (如 果实 现 的 话 ) 就 会 被 调用 多 少 次 ;由 于 只 
有 一 个 http{}， 所 以 create_main_conf 方 法 只 会 被 调用 一 次 。 这 3 个 方法 每 
被 调用 一 次 ， 就 会 生成 一 个 结构 体 ，Nginx 的 HTTP 框 架 居 然 创 建 了 如 此 
多 的 结构 体 来 存放 配置 项 ， 怎 样 理解 呢 ? 很 简单 ， 就 是 为 了 解决 同名 配 
置 项 的 合并 问题 。 








如 果实 现 了 create_main_conf 方 法 ， 它 所 创建 的 结构 体 只 会 存放 直接 
出 现在 http{} 块 下 的 配置 项 ， 那 么 create_main_conf 只 会 被 调用 一 次 。 


如 果实 现 了 create_srv_conf 方 法 ， 那 么 它 所 创建 的 结构 体 既 会 存放 
直接 出 现在 http{} 块 下 的 配置 项 ， 也 会 存放 直接 出 现在 server{} 块 下 的 配 
置 项 。 为 什么 呢 ? 这 其 实 是 HITP 框 架 的 一 种 优秀 设计 。 例 如 ， 虽 然 某 
个 配置 项 是 针对 于 server 虚 拟 主机 才 生 效 的 ， 但 http{} 下 面 可 能 有 多 个 
server{} 块 ， 对 于 用 户 来 说 ， 如 果 希 望 在 http{} 下 面 写 入 了 这 个 配置 项 后 
对 所 有 的 server{} 块 都 生效 ， 这 应 当 是 允许 的 ， 因 为 它 减 少 了 用 户 的 工 
作 量 。 而 对 于 HTTP 框 架 而 言 ， 就 需要 在 解析 直属 于 http{} 块 内 的 配置 项 
时 ， 调 用 create_srv_conf 方 法 产生 一 个 结构 体 存放 配置 ， 解 析 到 一 个 
server{} 块 时 再 调用 create_srv_conf 方 法 产生 一 个 结构 体 存 放 配 置 ， 最 后 
通过 把 这 两 个 结构 体 合并 解决 两 个 问题 ， 有 一 个 配置 项 在 http{} 块 内 出 
现 了 ， 在 server{} 块 内 却 没 有 出 现 ， 这 时 以 http 块 内 的 配置 项 为 准 ， 可 如 
果 这 个 配置 项 同时 在 http{} 块 、server{} 块 内 出 现 了 ， 它 们 的 值 又 不 一 
样 ， 此 时 应 当 由 对 它 感 兴趣 的 HTTP 模 块 来 决定 配置 项 以 哪个 为 准 。 











如 果实 现 了 create_ loc_conf 方 法 ， 那 么 它 所 创建 的 结构 体 将 会 出 现 
在 http{}、server{}、location{} 块 中 ， 理 由 同上 。 这 是 一 种 非常 人 性 化 的 
设计 ， 充 分 考虑 到 nginx.conf 文 件 中 高 级 别 的 配置 可 以 对 所 包含 的 低级 
别 配 置 起 作用 ， 同 时 也 给 出 了 不 同 级 别 下 同名 配置 项 冲突 时 的 解决 方案 
(可 以 由 HTTP 模 块 自行 决定 其 行为 ) 。4.3.3 节 中 将 讨论 HTTP 框 架 如 何 
合并 可 能 出 现 的 冲突 配置 项 。 在 10.2 节 会 详细 讨论 HTTP 框架 怎样 管理 
HTTP 模 块 产生 的 如 此 多 的 结构 体 ， 以 及 每 个 HITP 模 块 在 处 理 请 求 时 ， 
HTTP 框 架 又 是 怎样 把 正确 的 配置 结构 体 告 诉 它 的 。 





4.3.3 ”如 何 合并 配置 项 


在 4.3.1 市 描述 的 http 配 置 项 处 理 序 列 图 (图 4-1) 中 可 以 看 到 ， 在 第 
20 步 ，HTTP 框 架 开 始 合并 http{}、server{}、location{} 不 同 块 下 各 HTTP 
模块 生成 的 存放 配置 项 的 结构 体 ， 那 么 合并 配置 的 流程 是 怎样 进行 的 
呢 ? 本 节 将 简单 介绍 这 一 工作 流程 ， 而 在 10.2.4 节 中 会 利用 源 代码 完整 
地 说 明和 它 。 


图 4-4 是 合并 配置 项 过 程 的 活动 图 ， 它 主要 包含 四 大 部 分 内 容 。 


. 如 果 HTTIP 模 块 实现 了 merge_srv_conf 方 法 ， 就 将 http{...} 块 下 
cteate_strv_conf 生 成 的 结构 体 与 遍历 每 一 个 server{...} 配 置 块 下 的 结构 体 做 


merge_stv_conf 操 作 。 


如 果 HTTITP 模 块 实现 了 merge_loc_conf 方 法 ， 就 将 http{...} 块 下 
cteate_loc_conf 生 成 的 结构 体 与 谱 套 的 每 一 个 server{...} 配 置 块 下 生成 的 结 
构 体 做 merge_loc_conf 操 作 。 


如 果 HTTIP 模 块 实现 了 merge_loc_conf 方 法 ， 就 将 server{...} 块 下 
cteate_loc_conf 生 成 的 结构 体 与 谱 套 的 每 一 个 location{...} 配 置 块 下 
create_loc_conf 生 成 的 数据 结构 做 merge_loc_conf 操 作 。 


. 如 果 HTTP 模 块 实现 了 merge_loc_conf 方 法 ， 就 将 location{..….} 块 下 
create_Joc_conf 生 成 的 结构 体 与 继续 吝 套 的 每 一 个 location{...} 配置 块 下 
create_loc_conf 生 成 的 数据 结构 做 merge_loc_conf 操 作 。 注 意 ， 这 个 动作 
会 无 限 地 递归 下 去 ， 也 就 是 说 ，location 配 置 块 内 继续 识 套 location， 而 庶 
套 多 少 层 在 本 节 中 是 不 受 HTTP 框 架 限制 的 。 不 过 在 图 4-4 没 有 表达 出 无 
限 地 递归 处 理 座 套 location 块 的 意思 ， 仅 以 location 中 再 座 套 一 个 location 
作为 例子 简单 说 明 一 下 。 














依 序 遍 历 所 有 的 HTTP 模 块 
[获取 将 要 执行 合并 配置 项 的 HTTP 模 块 ] 


[已 经 处 理 完 所 有 HTTP 模 块 ] 





[遍历 到 一 个 HTTP 模块 ] 


[过 历 完 所 有 的 server 块 ] 
裔 历 当前 HTTP 模 抉 在 所 有 server 块 下 生成 的 结构 体 


[获取 该 HTTP 模 块 在 所 有 server 块 下 生成 的 结构 体 ] 


[获取 到 某 个 server 块 下 生成 的 结构 体 ] 


[ 如 果实 现 了 merge_srv _conf 方法 ] 
[没有 实现 merge_loc _conf ] [merge_srv _conf 方法 没有 实现 ] 


用 merge_srvy _conf 合并 htp 块 、server 块 下 create _srv _conf 产生 的 结构 体 


[是 否 实现 merge_loc _conf 方法 ] 


[遍历 完 所 有 的 location 块 ] 
[如 果实 现 了 merge_loc _conf 方法 ] 


用 merge_loc _conf 合并 http 块 、server 块 下 create _loc _conf 方法 产生 的 结构 体 


遍历 该 server 块 下 内 套 的 所 有 location 块 生成 的 结构 体 


[获取 该 HTTP 模块 在 所 有 location 块 下 生成 的 结构 体 ] 





[获取 到 location 块 ] 













用 merge_loc _conf 合并 server 块 、location 块 下 create_loc _conf 产生 的 结构 体 


遍历 完 所 有 的 子 location 块 ] 
毅 历 在 该 location 块 再 次 谋 套 的 所 有 location 块 下 生成 的 结构 体 
[获取 location 下 扰 套 的 location 块 ] 


[获取 到 子 location 块 ] 


用 merge_loc _conf 合并 location 块 和 其 峙 套 location 块 下 create_loc _conf 产生 的 结构 体 


图 4-4 解析 完 所 有 http 配 置 项 后 合并 配置 的 流程 图 


图 4-4 包 括 4 重 循环 ， 第 1 层 〈 最 外 层 ) 遍历 所 有 的 HITP 模 块 ， 第 2 
层 遍 历 所 有 的 server{...} 配 置 块 ， 第 3 层 是 遍历 某 个 serverf} 块 中 舱 套 的 所 
有 location{.….} 块 ， 第 4 层 遍 历 某 个 location{} 块 中 继续 向 套 的 所 有 location 
块 (实际 上 ， 它 会 一 直 递 归 下 去 以 解析 可 能 被 层 层 肉 套 的 location 块 ， 
详 见 10.2 节 ) 。 读 者 可 以 对 照 上 述 4 重 循环 来 理解 合并 配置 项 的 流程 
图 。 





4.3.4 预 设 配置 项 处 理 方法 的 工作 原理 


在 4.2.4 节 中 可 以 看 到 ， 自 定义 的 配置 项 处 理 方法 读 取 参 数值 也 是 很 
简单 的 ， 直 接 使 用 ngx_str_t*value=cf->args->elts; 就 可 以 获取 参数 。 接 下 
来 将 把 参数 赋值 到 ngx_http_mytest_conf t 结 构 体 的 相应 成 员 中 。 不 过 ， 
预 设 的 配置 项 处 理 方法 并 不 知道 每 个 HTTP 模 块 所 定义 的 结构 体 包括 哪 
些 成 员 ， 那 么 ， 它 们 怎么 可 以 做 到 具有 通用 性 的 呢 ? 


很 简单 ， 返 回 到 4.2.2 节 就 可 以 看 到 ，ngx_command t 结 构 体 的 offset 
成 员 已 经 进行 了 正确 的 设置 (实际 存储 参数 的 成 员 相 对 于 整个 结构 体 的 
偏 移 位 置 ) ，Nginx 配 置 项 解析 模块 在 调用 ngx_command_t 结 构 体 的 set 
回调 方法 时 ， 会 同时 把 offset 偏 移 位 置 传 进来 。 每 种 预 设 的 配置 项 解析 
方法 都 只 解析 特定 的 数据 结构 ， 也 就 是 说 ， 它 们 既 知 道 存储 参数 的 成 员 








相对 于 整个 结构 体 的 侦 移 量 ， 又 知道 这 个 成 员 的 数据 类 型 ， 目 然 可 以 做 
到 具有 通用 性 了 。 


下 面 以 读 取 数 字 配 置 项 的 方法 ngx_conf_set_num_slot 为 例 ， 说 明 预 
设 的 14 个 通用 方法 是 如 何 解 析 配 置 项 的 。 





char * ngx_conf_set_ num slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf) 





// 指针 


Conf 就 是 存储 参数 的 结构 体 的 地 址 


char *p = conf; 
ngx_int_t *np; 
ngx_str_t *value,; 
ngx_conf_post_t *post,; 
/* 根 据 


ngx_command 七 中 的 


offset 偏 移 量 ， 可 以 找到 结构 体 中 的 成 员 ， 而 对 于 


ngx_conf_set_num_slot 方 法 而 言 ， 存 储 数字 的 必须 是 





ngx_int 七 类 型 


np = (ngx_int t *) (p + cmd->offset); 
/* 在 这 里 可 以 知道 为 什么 要 把 使 用 


ngx_conf_set_num_slot 方 法 解析 的 成 员 在 





create_loc_conf 等 方法 中 初始 化 为 
NGX_CONF_UNSET， 否 则 是 会 报错 的 


*/ 
if (*np != NGX_CONF_UNSET) { 
return "is duplicate"; 
} 


// Value 将 指向 配置 项 的 参数 


value = cf->args->elts,; 
/* 将 字符 串 的 参数 转化 为 整 型 ， 并 设置 到 


create_loc_conf 等 方法 生成 的 结构 体 的 相关 成 员 上 


*/ 
*np = ngx_atoi(value[1].data, value[1].1en); 
if (*np == NGX_ERROR) { 
return "invalid number",; 
} 


// 如 果 
ngx_command_t 中 的 
post 已 经 实现 ， 那 么 还 需要 调用 


post->post_handler 方 法 


if (cmd->post) { 
post = cmd->post; 
return post->post_handler(cf, post, np); 


} 
return NGX_CONF_OKk; 





可 以 看 到 ， 这 是 一 种 非 第 灵活 和 巧妙 的 设计 。 


4.4 ”error 日 志 的 用 法 


Nginx 的 日 志 模 块 〈《 这 里 所 说 的 日 志 模 块 是 ngx_errlog_module 模 
块 ， 而 ngx_http_log_module 模 块 是 用 于 记录 HTTP 请 求 的 访问 日 志 的 ， 
两 者 功能 不 同 ， 在 实现 上 也 没有 任何 关系 ) 为 其 他 模块 提供 了 基本 的 记 
录 日 志 功 能 ， 本 章 提 到 的 mytest 模 块 当然 也 可 以 使 用 日 志 模块 提供 的 接 
口 。 出 于 路 平台 的 考虑 ， 日 志 模块 提供 了 相当 多 的 接口 ， 主 要 是 因为 有 
些 平 台 下 不 支持 可 变 参数 。 本 节 主 要 讨论 支持 可 变 参 数 的 日 志 接口 ， 事 
实 上 不 支持 可 变 参 数 的 日 志 接 口 在 实现 方面 与 其 并 没有 太 大 的 不 同 〈 参 
见 表 4-9) 。 首 先 看 一 下 日 志 模 块 对 于 支持 可 变 参 数 平台 而 提供 的 3 个 接 
Els 














#define ngx_log_error(level, log, args...) 
If ((10g)->log_ level >= level) ngx_log_error_core(level, log, args) 
#define ngx_log debug(level, lo0g, args...) 
if ((1og)->1og_level & level) \ 
ngx_1log_error_core(NGX_LOG_ DEBUG, log, args) 
void ngx_log_ error_core(ngx_uint_t lJevel, ngx_ log t *1og，ngx_err t err, const char 








Nginx 的 日 志 模 块 记录 日 志 的 核心 功能 是 由 ngx_log_error_core 方 法 
实现 的 ，ngx_log_error 宏 和 ngx_log_debug 宏 只 是 对 它 做 了 简单 的 封装 ， 


一 般 情 况 下 记录 日 志 时 只 需要 使 用 这 两 个 宏 。 








ngx_log_error 宏 和 ngx_log_debug 宏 都 包括 参数 level、log、err、 


fmt， 下 面 分 别 解 释 这 4 个 参数 的 意义 。 


(1) level 参 数 


对 于 ngx_log_error 宏 来 说 ，level 表 示 当 前 这 条 日 志 的 级 别 。 它 的 取 
值 范围 见 表 4-6。 


表 4-6 ngx_log_error 日 志 接 口 level 参 数 的 取 值 范围 





级 别名 称 意 义 
最 高 级 别 日 志 ， 日 志 的 内 容 不 会 表 写 入 log 参数 指定 的 文件 ， 而 是 会 直接 将 
NGX LOG STDERR 最 高 级 别 a J On , 3 数 指定 的 文件 是 会 直接 将 
日 志 输 出 到 标准 错误 设备 ， 如 控制 台 屏 幕 
大 于 NGX LOG _ ALERT 级别， 而 小 于 或 等 于 NGX _ LOG EMERG 级 别 的 
NGX LOG EMERG 1 上 和 
日 志 都 会 输出 到 log 参数 指定 的 文件 中 


没 
ba 


级 别名 称 
NGX_LOG ALERT 
NGX_LOG CRIT 
NGX_LOG ERR 
NGX_LOG WARN 
NGX_LOG NOTICE 
NGX_LOG INFO 
NGX_LOG DEBUG 


大 于 NGX_LOG CRIT 级 别 

大 于 NGX_LOG ERR 级 别 

-于 NGX LOG WARN 级 别 
大 于 NGX LOG NOTICE 级 别 
大 于 NGX _ LOG INFO 级 别 

大 于 NGX_ LOG_DEBUG 级 别 


调试 级 别 ， 最 低级 别 日 志 





站 





使 用 ngx_log_error 宏 记录 日 志 时 ， 如 果 传 入 的 level 级 别 小 于 或 等 于 
log 参 数 中 的 日 志 级 别 〈 通 常 是 由 nginx.conf 配 置 文件 中 指定 ) ， 就 会 输 
出 日 志 内 容 ， 人 否则 这 条 日 志 会 被 忽略 。 


在 使 用 ngx_log_debug 宏 时 ，level 的 意义 完全 不 同 ， 它 表达 的 意义 不 

再 是 级 别 (已 经 是 DEBUG 级 别 ) ， 而 是 日 志 类 型 ， 因 为 ngx_log_debug 

宏 记 录 的 日 志 必 须 是 NGX_LOG_DEBUG 调 试 级 别 的 ， 这 里 的 level 由 各 
子 模块 定义 。level 的 取 值 范围 参见 表 4-7。 


表 4-7 ngx_log _ debug 上 日志 接口 level 参 数 的 取 值 范围 








级 别名 称 意 义 
NGX LOG DEBUG CORE Nginx 核心 模块 的 调试 日 志 
NGX LOG DEBUG ALLOC Nginx 在 分 配 内 存 时 使 用 的 调试 日 志 
NGX LOG DEBUG MUTEX Nginx 在 使 用 进程 锁 时 使 用 的 调试 日 志 
NGX LOG DEBUG EVENT Nginx 事件 模块 的 调试 日 志 
NGX LOG DEBUG HTTP Nginx http 模块 的 调试 日 志 
NGX LOG DEBUG MAIL Nginx 邮件 模块 的 调试 日 志 
NGX LOG DEBUG MYSQL 表示 与 MySQL 相关 的 Nginx 模块 所 使 用 的 调试 日 志 





当 HTTP 模 块 调用 ngx_log_debug 宏 记录 日 志 时 ， 传 入 的 level 参 数 是 
NGX_LOG_DEBUG_HTTP， 这 时 如 果 ]og 参 数 不 属 于 HTTP 模 块 ， 如 使 
用 了 event 事 件 模块 的 og， 则 不 会 输出 任何 日 志 。 它 正 是 ngx_log_debug 
拥有 level 参 数 的 意义 所 在 。 


(2) log 参 数 


实际 上 ， 在 开发 HTTP 模 块 时 我 们 并 不 用 关心 log 参 数 的 构造 ， 因 为 
在 处 理 请 求 时 ngx_http_request_t 结 构 中 的 connection 成 员 就 有 一 个 
ngx_log_t 类 型 的 log 成 员 ， 可 以 传 给 ngx_log_error 宏 和 ngx_log_debug 宏 
记录 日 志 。 在 读 取 配 置 阶段 ，ngx_conf_t 结 构 也 有 log 成 员 可 以 用 来 记录 
志 “〈 读 取 配 置 阶段 时 的 日 志 信息 都 将 输出 到 控制 台 屏 幕 ) 。 下 面 简单 
地 看 一 下 ngx_log_t 的 定义 。 











typedef struct ngx_log_s ngx_log_t; 
typedef u_char *(*ngx_log handler_pt) (ngx_ log t *1og，UuU_char *buf, size t len); 
struct ngx_log_s 

// 日 志 级 别 或 者 日 志 类 型 





ngx_uint_t log_level; 


// 日 志文 件 


ngx_open_ file t *file; 
// 连接 数 ， 不 为 


0 时 会 输出 到 日 志 中 


ngx_atomic uint_t connection,; 
/* 记 录 日 志 时 的 回调 方法 。 当 


handler 已 经 实现 (不 为 


NULL) ， 并 且 不 是 


DEBUG 调 试 级 别 时 ， 才 会 调用 


handJlLer 钩 子 方法 


4 
ngx_]1og_handler_pt handJler 
/* 每 个 模块 都 可 以 自 定义 


data 的 使 用 方法 。 通 常 ， 


data 参 数 都 是 在 实现 了 上 面 的 


handler 回 调 方法 后 才 使 用 的 。 例 如 ， 


HTTP 框 架 就 定义 了 


handler 方 法 ， 并 在 


data 中 放 入 了 这 个 请 求 的 上 下 文 信息 ， 这 样 每 次 输出 日 志 时 都 会 把 这 个 请 求 


URI 输 出 到 日 志 的 尾部 


*/ 
void *data; 
/* 表 示 当 前 的 动作 。 实 际 上 ， 


action 与 


data 是 一 样 的 ， 只 有 在 实现 了 


handler 回 调 方法 后 才 会 使 用 。 例 如 ， 


HTTP 框 架 就 在 


handler 方 法 中 检查 


action 是 否 为 


NULL， 如 果 不 为 


NULL ， 就 会 在 日 志 后 加 入 “ 


while ” 


+action， 以 此 表示 当前 日 志 是 在 进行 什么 操作 ， 帮 助 定 位 问题 


}; 


char *action; 








可 以 看 到 ， 如 果 只 是 想 把 相应 的 信息 记录 到 日 志文 件 中 ， 那 么 完全 
不 需要 关心 ngx_log t 类 型 的 log 参 数 是 如 何 构造 的 。 特 别 是 在 编写 HITP 
模块 时 ，HTTP 框 架 要 求 所 有 的 HTTP 模 块 都 使 用 它 提供 的 log， 如 果 重 
定义 ngx_log_t 中 的 handler 方 法 ， 或 者 修改 data 指 向 的 地 址 ， 那 么 很 可 能 


会 造成 一 系列 问题 。 


然而 ， 从 上 文 对 ngx_log_t 结 构 的 摘 述 中 可 以 看 出 ， 如 果 定 义 一 种 新 
的 模块 〈 不 是 HTTP 模 块 ) ， 那 么 日 志 模 块 提供 很 强大 的 功能 ， 可 以 把 
一 些 通用 化 的 工作 都 放 到 handler 回 调 方法 中 实现 。 


(3) err 参 数 


err 人 参数 就 是 错误 码 ， 一 般 是 执行 系统 调用 失败 后 取得 的 errno 参 
数 。 当 err 不 为 0 时 ，Nginx 日 志 模 块 将 会 在 正常 日 志 内 容 前 输出 这 个 错误 
码 以 及 其 对 应 的 字符 串 形 式 的 错误 消息 。 





(4) fmt 参 数 


fmt 就 是 可 变 参 数 ， 就 像 在 printf 等 C 语 言 方 法 中 的 输入 一 样 。 例 
如 : 





ngx_log_error(NGX_LOG ALERT, r->connection->lo0g,0, 
"test_flag=%d, test_str=%V, path=%*s,mycf addr=%p", 
mycf->my_flag, 
&mycf->my_str, 
mycf->my_path->name.1en, 
mycf->my_path->name.data, 
mycf ); 





fmt 的 大 部 分 规则 与 printf 等 通用 可 变 参数 是 一 致 的 ， 然 而 Nginx 为 了 
方便 它 自 定 义 的 数据 类 型 ， 重 新 实现 了 基本 的 ngx_vslprintf 方 法 。 例 
如 ， 增 加 了 诸如 %V 等 这 样 的 转换 类 型 ，%V 后 可 加 ngx_str_t 类 型 的 变 
量 ， 这 些 都 是 普通 的 printf 中 没有 的 。 表 4-8 列 出 了 ngx_vslprintf 中 支持 的 
27 种 转换 格式 。 


@ 注意 ptintf 或 者 sptintf 支 持 的 一 些 转换 格式 在 ngx_vslptintf 中 是 
不 支持 的 ， 或 者 意义 不 同 。 


表 4-8 打印 日 志 或 者 使 用 ngx_sptintf 系 列 方法 转换 字符 串 时 支持 的 27 种 
转化 格式 


转换 格式 
9%00 


%m 


%X 


Sox 


%. 


%f 


os 


os 


%V 


9%6v 


%O 
%P 
%T 
%oM 
9%z 
Yoi 
%d 
941 
%D 
%L 
%A 


or 


%p 
9%6ec 
2%Z 
oN 
9694 


用 法 

表示 无 符号 ， 其 后 还 可 以 跟 其 他 转换 符号 ， 如 %ui 表示 要 转换 的 类 型 是 ngx_uint_ t。 如果 其 后 没有 
腿 转 换 符 号 ， 则 表示 要 转换 的 类 型 是 无 符号 十 进 制 正 数 

表示 以 最 大 长 度 来 转换 数字 类 增 (如 int) 

以 十 六 进 制 来 格式 化 转换 后 的 数据 。 注意 . Nginx 中 的 %X 与 printf 等 转换 格式 完全 不 同 ， 它 只 是 
限制 转换 后 的 数字 以 十 六 进 制 格式 来 显示 ， 而 不 是 限制 相应 参数 的 类 型 。 例 如 , %Xd 后 跟着 int 类 型 , 
表示 以 十 六 进 制 格式 来 显示 int 整数 ， 而 %Xp 表示 以 十 六 进 制 格式 来 显示 指针 地 址 。 如 漆 仅 有 %X， 
那么 蚌 没 有 任何 输出 的 

%x 与 %X 的 用 法 完全 相同 ， 只 是 %X 以 A、B、C、D、E、F 表示 十 进 制 中 的 10、11、12、13、 
14、15， 而 %x 是 以 小 写 的 a、b、c、d、e、f{ 来 表示 

其 后 必须 紧 跟 数字 - 当前 实现 版 本 下 必须 与 %f 配合 使 用 ， 表 示 转 换 浮 点 数 时 小 数 部 分 的 位 数 。 例 
如 ，%.10f 表示 转换 double 类 型 时 ,小数点 后 转换 且 必 须 转换 为 10 位 ,不 足 10 位 以 0 填补 

转换 double 类 型 数据 。 注 意 ， 它 与 printf 等 标准 C 语言 中 的 %f 完 全 不 同 ， 如 果 想 转换 小 数 部 分 ， 
则 必须 加 上 %.(numberjf- 参见 本 表 中 %. 的 描述 

表示 要 转换 的 字符 长 度 。 目 前 仅 与 %s 配合 使 用 

转换 1 个 char* 或 者 u_char* 的 字符 串 。 与 %* 配合 使 用 时 ，%*s 表示 输出 指定 长 度 的 字符 串 ， 其 
后 必须 有 两 个 参数 : 表示 输出 字符 串 长 度 的 size t 和 字符 只 地 址 char* 类 型 。 如果 不 与 %* 配合 使 用 ， 
而 与 print 等 标准 格式 相同 ， 那 么 字符 尝 必 须 以 “\0 ”结尾 

转换 ngx_str 类 型 ，%V 对 应 的 参数 必须 是 ngx_str (变量 的 地 址 。 它 将 会 按照 ngx_str t 类 型 的 
len 长 度 来 输出 data 字符 串 

转换 ngx_variable_value_t 类 型 。%yvy 对 应 的 参数 必须 是 ngx_variable_value_t 变量 的 地 址 。 它 将 会 按 
妥 ngx_variable_value t 类 型 的 len 长 度 来 输出 data 字符 串 

转换 1 个 off + 类 型 

转换 1 个 ngx_pid +t 类 再 

转换 1 个 time_t 类 型 

转换 1 个 ngx_msec {类 型 

转换 ssize + 类 型 数据 ， 如 果 用 %uz， 则 转换 的 数据 类 型 是 size_t 

转换 ngx_int t 型 数据 ， 如 果 用 %ui， 则 转换 的 数据 类 型 是 ngx_uint 1 

转换 int 型 数据 ， 如 果 用 %ud， 则 转换 的 数据 类 型 是 u int 

转换 long 型 数据 ， 如 果 用 %ul， 则 转换 的 数据 类 型 是 u_long 

转换 int32 + 型 数据 ， 如 果 用 %uD， 则 转 撞 的 数据 类 型 是 uint32_+ 

转换 int64 .+ 型 数据 ， 如 果 用 %uL ， 则 转换 的 数据 类 型 是 uint64 1 

转换 ngx_atomic_int + 型 数据 ， 和 如 上 业 用 %uA， 则 转换 的 数据 类 型 是 ngx_atomic_uint t 

转换 1 个 rlim tt 类型。 系统 调用 getrlimit 或 者 setrlimit 时 都 会 使 用 rlim_t 类 型 参数 ， 它 实际 上 是 一 
个 算术 数据 类 型 ， 等 同 于 类 型 int、size { 或 者 off + 

转换 1 个 指针 (地 址 ) 

转换 1 个 字符 类 型 

表示 "0 

表示 Wn' 换行 符 ， 即 "x0a"， 在 windows 操作 系统 上 则 表示 Won'， 也 就 是 \x0d\x0a" 

打印 1 个 百 分 号 (%) 


例如 ， 在 4.2.4 节 自 定义 的 ngx_conf_set_myconfig 方 法 中 ， 可 以 这 样 
输出 日 志 。 





long tl = 4900000000 ; 
u_long tul = 5000000000 ; 
int32_t ti32 = 110; 


ngx_str_t tstr = ngx_string("teststr"); 
double tdoub = 3.1415926535897932，; 
int x = 15; 


ngx_log_error(NGX LOG ALERT, cf->l0g, 09, 
"1=%]1, ul=%ul, D=%D, p=%p, f=%. 10f, str=%V, x=%xd, X=%Xd", 
t1, tul, ti32,&ti32,tdoub,&tstr, x,x); 








上 述 这 上 段 代 码 将 会 输出 : 





nginx: [alert] 1=4900000000,ul=5000000000,D=110,p=00007FFFF26B36DC, f=3.1415926536, st 





在 Nginx 的 许多 核心 模块 中 可 以 看 到 ， 它 们 多 使 用 的 是 debug 调 试 级 
别 的 日 志 接 口 ， 见 表 4-9。 


表 4-9 Nginx 提 供 的 不 支持 可 变 参 数 的 调试 日 志 接 口 


日 志 接口 


ngx log debug0 


使 用 参数 
ngx log debug0(level. log. err, fmt) 


ngx_log_debugl | fmt 格式 后 只 接受 1 个 参 类 ngx log debugl(level. log.e 


所 


T, fint, argl) 


ngx_log_debug2 | fmt 格式 后 只 接受 2 个 参 妆 ngx_ log debug2(level, log. err. fmt, argl, arg2) 
ngx_log_debug3 |fmt 格式 后 只 接 一 
ngx_ log _ debug4 | fmt 格式 后 只 接受 


ngx_log_debug5 | fmt 格式 后 人 5 个 参 妆 ngx_ log debug5 (level, log. err. fmt. argl, arg2. arg3, arg4. arg5) 


ngx_log debug3(level. log. err. fmt. argl. arg2. arg3) 


ngx log debug4(level, log. err, fimt, argl, arg2, arg3. arg4) 


ngx_ log_debug6 | fmt 格式 后 只 接受 6 个 参 娄 ngx log debug6(level, log. err. fmt, argl, arg2, arg3, arg4. arg5, arg6) 


ngx_log_debug7 | fmt 格式 后 只 接受 7 个 参 类 ngx log debug7(level, log. em fimt. argl, arg2, arg3, arg4. argS. arg6, arg7) 
i ngx_log debug8(level. log, err, fmt. argl. arg2, arg3, arg4, arg5. arg6, 
ngx_log_debug8 | fmt 格式 后 只 接受 8 





arg7. arg8) 


处 5， 请求 的 了 上 下文 


在 Nginx 中 ， 上 下 文 有 很 多 种 含义 ， 然 而 本 节 描 述 的 上 下 文 是 指 
HTTP 框 架 为 每 个 HTTP 请 求 所 准备 的 结构 体 。HTTP 框 架 定义 的 这 个 上 
下 文 是 针对 于 HTTP 请 求 的 ， 而 且 一 个 HTTP 请 求 对 应 于 每 一 个 HTTP 模 
块 都 可 以 有 一 个 独立 的 上 下 文 结构 体 〈 并 不 是 一 个 请 求 的 上 下 文 由 所 有 
HTTP 模 块 共 用 )。 





4.5.1 上 下 文 与 全 异步 Web 服 务 器 的 关系 


上 下 文 是 什么 ?简单 地 讲 ， 就 是 在 一 个 请 求 的 处 理 过 程 中 ， 用 类 似 
struct 这 样 的 结构 体 把 一 些 关 键 的 信息 都 保存 下 来 ， 这 个 结构 体 可 以 称 
为 请 求 的 上 下 文 。 每 个 HTTP 模 块 都 可 以 有 上 自己 的 上 下 文 结构 体 ， 一 般 
都 是 在 刚 开 始 处 理 请 求 时 在 内 存 池 上 分 配 它 ， 之 后 当 经 由 epoll、HTTP 
框架 再 次 调用 到 HTTP 模 块 的 处 理 方法 时 ， 这 个 HTTP 模块 可 以 由 请 求 的 
上 下 文 结构 体 中 获取 信息 。 请 求 结束 时 就 会 销毁 该 请 求 的 内 存 池 ， 自 然 
也 就 销毁 了 上 下 文 结构 体 。 以 上 就 是 HITP 请 求 上 下 文 的 使 用 场景 ， 由 
于 1 个 上 下 文 结构 体 是 仅 对 1 个 请 求 1 个 模块 而 言 的 ， 所 以 它 是 低 耦 合 
的 。 如 果 这 个 模块 不 需要 使 用 上 下 文 ， 也 可 以 完全 不 理会 HTTP 上 下 文 


这 个 概念 。 











那么 ， 为 什么 要 定义 HITP 上 下 文 这 个 概念 呢 ? 因为 Nginx 是 个 强大 
的 全 异步 处 理 的 Web 服 务 器 ， 意 味 着 1 个 请 求 并 不 会 在 epoll 的 1 次 调度 中 
处 理 完 成 ， 甚 至 可 能 成 千 上 万 次 的 调度 各 个 HTTP 模 块 后 才能 完成 请 求 
的 处 理 。 











怎么 理解 上 面 这 句 话 呢 ? 以 Apache 服 务 器 为 例 ，Apache 就 像 某 些 高 
档 餐 厅 ， 每 位 客人 《HITP 请 求 ) 都 有 1 位 服务 员 《〈 一 个 Apache 进 程 ) 全 
程 服务 ， 每 位 服务 员 只 有 从 头 至 尾 服务 完 这 位 客人 后 ， 才 能 去 为 下 一 个 
客人 提供 服务 。 因 此 餐厅 的 并 发 处 理 数 量 受 制 于 服务 员 的 数量 ， 但 服务 
员 的 数量 也 不 是 越 多 越 好 ， 因 为 餐厅 的 固定 设施 (CPU) 是 有 限 的 ， 它 
的 管理 成 本 (Linux 内核 的 进程 切换 成 本 〉 也 会 随 着 服务 员 数 量 的 增加 
而 提高 ， 最 终 影响 服务 质量 。Nginx 则 不 同 ， 它 就 像 Playfirst 公 司 在 2005 
年 发 布 的 休闲 游戏 《美女 餐厅 》 一 样 ，1 位 服务 员 同 时 处 理 所 有 客人 的 
需求 。 当 1 位 客人 进入 餐厅 后 ， 服 务 员 首先 给 它 安排 好 蝎子 并 把 沫 单 给 
客人 后 就 离开 了 ， 继 续 服务 于 其 他 客人 。 当 这 位 客人 决定 点 哪些 沫 后 ， 
就 试图 去 叫 服务 员 过 来 处 理 点 染 需求 ， 当 然 ， 服 务 员 可 能 正在 忙于 其 他 
客人 ， 但 只 要 一 有 空闲 就 会 过 来 拿 菜单 并 交 给 厨房 ， 再 去 服务 于 其 他 客 
人 。 直 到 厨房 通知 这 位 客人 的 染 已 毫 饪 完毕 ， 服 务 员 再 取 来 菜 主 动 地 传 
递 给 客人 ， 请 他 用 和 餐 ， 之 后 服务 员 义 去 寻找 是 否 有 其 他 客人 在 等 待 服 
务 。 





























可 以 注意 到 ， 当 1 位 客人 进入 Nginx“ 和 餐厅 ”时 ， 首 先是 由 客人 来 “ 激 


活 ?Nginx“ 服 务 员 ”的 。Nginx“ 服 务 员 ”再 次 来 处 理 这 位 客人 的 请 求 时 ， 

有 可 能 是 因为 这 位 客人 点 完 来 后 大 声 地 叫 Nginx“ 服 务 员 ”， 等 候 她 来 服 
务 ， 也 有 可 能 是 因为 厨房 做 好 沫 后 厨师 "激活 ?了 这 位 客人 的 服务 ， 也 就 
古 说 “激活 ?Nginx“ 服 务 员 ”的 对 象 是 不 固定 的 。 餐 厅 的 流程 是 移 点 沫 ， 

再 上 和 沫 ， 最 后 收 账 单 以 及 撤 碗 盘 ， 但 客人 是 不 想 了 解 这 个 流程 的 ， 所 以 
Nginx“ 服 务 员 ” 需 要 为 每 位 客人 建立 上 下 文 结构 体 来 表示 客人 进行 到 哪 
个 步骤 ， 即 他 点 了 哪些 菜 、 目 前 已 经 上 了 哪些 菜 ， 这 些 信 息 都 需要 独立 
的 保存 。“ 服 务 员 ”不 会 去 记 住 所 有 客人 的 “上 下 文 信息 ”因为 要 同时 服 
务 的 客人 可 能 很 多 ， 只 有 在 服务 到 茶 位 客人 时 才 会 去 得 对 应 的 “上 下 文 


兰 由”% 
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上 面 说 的 Nginx“ 服 务 员 ”就 像 Nginx worker 进 程 ， 客 人 就 是 一 个 个 请 
求 ， 一 个 Nginx 进 程 同 时 可 以 处 理 百 万 级 别 的 并 发 HTTP 请 求 。 厨 房 这 些 
设施 可 能 是 网 卡 、 硬 盘 等 硬件 。 因 此 ， 如 果 我 们 开发 的 HTTP 模 块 会 多 
次 反复 处 理 同 1 个 请 求 ， 那 么 必须 定义 上 下 文 结构 体 来 保存 处 理 过 程 的 
中 间 状 态 ， 因 为 谁 也 不 知道 下 一 次 是 由 网 卡 还 是 硬盘 等 服务 来 激活 
Nginx 进 程 继续 处 理 这 个 请 求 。Nginx 框 架 不 会 维护 这 个 上 下 文 ， 只 能 
这 个 请 求 自己 保存 着 上 下 文 结构 体 。 














再 把 这 个 例子 对 应 到 HTTP 框 架 中 。 点 菜 可 能 是 一 件 非常 复杂 的 
事 ， 因 为 可 能 涉及 凉菜 、 热 菜 、 汤 、 甜 品 等 。 假 如 HTTP 模 块 A 负 责 凉 
菜 、HTTP 模 块 B 负 责 热 荣 、HTTP 模 块 C 负 责 汤 。 当 一 位 新 客人 到 来 





后 ， 他 招呼 着 服务 员 (worker 进 程 》 和 HTTP 框 架 处 理 他 的 点 菜 需 求 时 
(假设 他 想 点 2 个 凉菜 、5 个 热 菜 、1 个 汤 ) ，HTTP 模 块 A 刚 处 理 了 1 个 
凉菜 ， 又 有 其 他 客人 将 服务 员 叫 走 了 ， 那 么 ， 这 个 客人 处 必须 有 一 张 纸 
记录 着 关于 凉菜 刚 点 了 一 个 ， 另 一 张 纸 记录 着 热 菜 一 个 没 点 ， 由 于 
HTTP 模 块 C 知 道 ， 当 前 的 餐厅 汤 已 经 卖 完 ， 业 务实 在 是 太 简单 了 【回顾 
一 下 第 3 章 的 helloword 例 子 ) ， 所 以 不 需要 再 有 一 张 纸 记录 着 汤 有 没有 
点 。 这 两 张 纸 只 从 属于 这 个 客人 ， 对 于 其 他 客人 没有 意义 ， 这 就 是 上 面 
所 说 的 ， 上 下 文 只 是 对 于 一 个 请 求 而 言 。 同 时 ， 每 个 HTTP 模 块 都 可 以 
拥有 记录 客人 《请 求 ) 状态 的 纸 ， 这 张 纸 就 其 实 就 是 上 下 文 结 构 体 。 当 
这 个 客人 叫 来 服务 员 时 ， 各 个 HTTP 模 块 可 以 查看 客人 身 前 的 两 张 纸 ， 
了 解 到 点 了 哪些 荣 ， 这 才 可 以 继续 处 理 下 去 。 


























在 第 3 章 中 的 例子 中 虽然 没有 使 用 到 上 下 文 ， 但 也 完成 了 许多 功 
能 ， 这 是 因为 第 3 章 中 的 mytest 模 块 对 同 1 个 请 求 只 处 理 了 一 次 (发 送 响 
应 包 时 虽然 有 许多 次 调用 ， 但 这 些 调用 是 由 HTTP 框 架 帮 助 我 们 完成 
的 ， 并 没有 再 次 回调 mytest 模 块 中 的 方法 ) ， 它 的 功能 非常 简单 。 在 第 5 
半 中 可 以 看 到 ， 无 论 是 subrequest 还 是 upstream， 都 必须 有 上 下 文 结构 体 
来 文 持 异步 地 访问 第 三 方 服 务 。 











4.5.2 ”如 何 使 用 HTTP 上 下 文 


ngx_http_get_module_ctx 和 ngx_http_set_ctx 这 两 个 宏 可 以 完成 HTTP 


上 下 文 的 设置 和 使 用 。 先 看 看 这 两 个 宏 的 定义 ， 如 下 所 示 。 





#define ngx_http_get module ctx(r, module) (r)->ctx[module.ctx_index] 
#define ngx_http_set_ ctx(r, c, module) r->ctx[module.ctx_ index] = c; 











ngx_http_get_module_ctx 接 受 两 个 参数 ， 其 中 第 1 个 参数 是 
ngx_http_request_t 指 针 ， 第 2 个 参数 则 是 当前 的 HTTP 模 块 对 象 。 例 如 ， 
在 mytest 模 块 中 使 用 的 就 是 在 3.5 节 中 定义 的 ngx_module _t 类 型 的 
ngx_http_mytest_module 结 构 体 。ngx_http_get_module_ctx 返 回 值 就 是 某 
个 HTTP 模 块 的 上 下 文 结构 体 指 针 ， 如 果 这 个 HTTP 模 块 没 有 设置 过 上 下 
文 ， 那 么 将 会 返回 NULL 空 指针 。 因 此 ， 在 任何 一 个 HTTP 模 块 中 ， 都 可 
以 使 用 ngx_http_get_module_ctx 获 取 所 有 HTTP 模 块 为 该 请 求 创建 的 上 下 
文 结构 体 。 








ngx_http_set_ctx 接 受 3 个 参数 ， 其 中 第 1 个 参数 是 ngx_http_request_t 
指针 ， 第 2 个 参数 是 准备 设置 的 上 下 文 结构 体 的 指针 ， 第 3 个 参数 则 是 
HTTP 模 块 对 象 。 





举 个 简单 的 例子 来 说 明 如 何 使 用 ngx_http_get_module_ctx 宏 和 
ngx_http_set_ctx 宏 。 首 先 建立 mytest 模 块 的 上 下 文 结构 体 ， 如 


ngx_http_mytest_ctx_t。 





typedef struct { 
ngx_uint_t my_step; 
} ngx_http_mytest_ctx tt， 








当 请 求 第 1 次 进入 mytest 模 块 处 理 时 ， 创 建 ngx_http_mytest_ctx_t 结 
构 体 ， 并 设置 到 这 个 请 求 的 上 下 文中 。 





static ngx_int 
ngx_http_mytest_handler(ngx_http_request_t *r) 


// 首先 调用 





ngx_http_get_module_ctx 宏 来 获取 上 下 文 结 构 体 


ngx_http_mytest_ctx_t* myctx = ngx_http_get module ctx(r,ngx_http_mytest_ module, 
// 如 果 之 前 没有 设置 过 上 下 文 ， 那 么 应 当 返 回 








NULL 
if (myctx == NULL) 


/* 必 须 在 当前 请 求 的 内 存 池 


r->pool1 中 分 配 上 下 文 结构 体 ， 这 样 请 求 结 束 时 结构 体 占 用 的 内 存 才 会 释放 


*/ 
myctx = ngx_palloc(r->pool, sizeof(ngx_http_mytest_ctx_t)); 
if (myctx == NULL) 
{ 
return NGX_ERROR; 





} 
// 将 刚 分 配 的 结构 体 设 置 到 当前 请 求 的 上 下 文中 


ngx_http_set_ctx(r,myctx,ngx_http_mytest_module); 


} 
// 之 后 可 以 任意 使 用 


myctx 这 个 上 下 文 结构 体 





如 果 Nginx 多 次 回调 mytest 模 块 的 相应 方法 ， 那 么 每 次 用 
ngx_http_get_module_ctx 宏 取 到 上 下 文 ，ngx_http_mytest_ctx_t 都 可 以 正 


第 使 用 ，HTTP 框 架 可 以 对 一 个 请 求 保 证 ， 无 论调 用 多 少 次 
ngx_http_get_module_ctx 宏 都 只 取 到 同一 个 上 下 文 结构 。 


4.5.3 ” HTTP 框架 如 何 维护 上 下 文 结构 


首先 看 一 下 ngx_http_request_t 结 构 的 ctx 成 员 。 





struct ngx_http_redquest_s { 


void **ctx; 





可 以 看 到 ，ctx 与 4.3.2 节 中 ngx_http_conf_ctx_t 结 构 的 3 个 数组 成 员 非 
党 相似 ， 它 们 都 表示 指 同 void* 指 针 的 数组 。HTTP 框 染 就 是 在 ctx 数 组 中 
保存 所 有 HTTP 模 块 上 下 文 结构 体 的 指针 的 。 


HTTP 框 架 在 开始 处 理 1 个 HITP 请 求 时 ， 会 在 创建 
ngx_http_request_t 结 构 后 ， 建 立 ctx 数 组 来 存储 所 有 HTTP 模 块 的 上 下 文 
结构 体 指针 〈 请 求 ngx_http_request_t 的 ctx 成 员 是 一 个 指针 数组 ， 其 初始 
化 详 见 图 11-2 的 第 9 步 ) 。 








r->ctx = ngx_pcalloc(r->pool, sizeof(void*)*ngx_http_max_module); 
If (r->ctx == NULL) { 

ngx_destroy_pool(r->pool); 

ngx_http_close_connection(c); 

return; 


} 





对 比 4.5.2 节 中 的 两 个 宏 的 定义 可 以 看 出 ，ngx_http_get_module_ctx 


和 ngx_http_set_ctx 只 是 去 获取 或 者 设置 ctx 数 组 中 相应 HITP 模 块 的 指针 
而 已 。 


4.6 “小 第 


通过 第 3 章 ， 我 们 已 经 了 解 到 开发 一 个 基本 的 HTTP 模块 可 以 非常 简 
单 ， 而 本 章 介 绍 的 读 取 配置 项 、 使 用 日 志 记 录 必 要 信息 、 为 每 个 HTTP 
请 求 定义 上 下 文 则 是 开发 功能 灵活 、 复 杂 、 高 性 能 的 Nginx 模 块 时 必须 
了 解 的 机 制 。 熟 练 掌握 本 章 内 容 ， 是 开发 每 一 个 产品 级 别 HTTP 模 块 的 
先决 条 件 。 











第 5 草 访问 第 三 方 服务 











当 需 要 访问 第 三 方 服务 时 ，Nginx 提 供 了 两 种 全 异步 方式 来 与 第 三 
方 服务 器 通信 : upstream 与 subrequest。upstream 可 以 保证 在 与 第 三 方 服 
务 器 交互 时 (包括 三 次 握手 建立 TCP 连 接 、 发 送 请 求 、 接 收 响应 、 四 次 
握手 关闭 TCP 连 接 等 ) 不 会 阻塞 Nginx 进 程 处 理 其 他 请 求 ， 也 就 是 说 ， 
Nginx 仍 然 可 以 保持 它 的 高 性 能 。 因 此 ， 在 开发 HTTP 模 块 时 ， 如 果 需 要 
访问 第 三 方 服务 是 不 能 自己 简单 地 用 套 接 字 编程 实现 的 ， 这 样 会 破坏 
Nginx 优 秀 的 全 异步 架构 。subrequest 只 是 分 解 复杂 请 求 的 一 种 设计 模 
式 ， 它 本 质 上 与 访问 第 三 方 服务 没有 任何 关系 ,但 从 HTTP 模 块 开 发 者 
的 角度 而 言 ， 使 用 subrequest 访 问 第 三 方 服务 却 很 常用 ， 当 然 ， 
subrequest 访 问 第 三 方 服务 最 终 也 是 基于 upstream 实 现 的 。 这 两 种 机 制 是 
HTTP 框 染 为 用 户 准 备 的 、 无 阻 徐 访问 第 三 方 服务 的 利器 。 








upstream 和 subrequest 的 设计 目标 是 完全 不 同 的 。 从 名 称 中 可 以 看 
出 ，upstream 被 定义 为 访问 上 游 服 务 器 ， 也 就 是 说 ， 它 把 Nginx 定 义 为 代 
理 服务 器 ， 首 要 功能 是 透 传 ， 其 次 才 是 以 TCP 获 取 第 三 方 服 务 器 的 内 
容 。Nginx 的 HITP 反 向 代理 模块 就 是 基于 upstream 方 式 实现 的 。 顾 名 思 
义 ，subrequest 是 从 属 请 求 的 意思 ， 在 这 里 我 们 更 倾向 于 称 它 为 子 请 
求 ， 也 束 是 说 ，subrequest 将 会 为 客户 请 求 创建 子 请 求 ， 这 是 为 什么 
呢 ? 因为 异步 无 阻塞 程序 的 开发 过 于 复杂 ， 上 所 以 HTTP 框架 提供 了 这 种 











机 制 将 一 个 复杂 的 请 求 分 解 为 多 个 子 请 求 ， 每 个 子 请 求 负责 一 种 功能 ， 
而 最 初 的 原始 请 求 负责 构 成 并 发 送 响应 给 客户 端 。 例 如 ， 用 subrequest 
访问 第 三 方 服务 ， 一 般 都 是 派生 出 子 请 求 访问 上 游 服 务 器 ， 父 请 求 在 完 
全 取得 上 游 服 务 器 的 响应 后 再 决定 如 何 处 理 来 自 客户 端的 请 求 。 这 样 做 
的 好 处 是 每 个 子 请 求 专注 于 一 种 功能 。 例 如 ， 对 于 一 个 子 请 求 ， 通 常 在 
NGX_HTTP_CONTENT_PHASE 阶 段 仅 会 使 用 一 个 HITP 模 块 处 理 ， 这 
大 大 降低 了 模块 开发 的 复杂 度 。 从 HTTP 框 架 的 内 部 来 说 ，subrequest 与 
upstream 也 完全 不 同 ，upstream 是 从 属于 用 户 请 求 的 ，subrequest 与 原始 
的 用 户 请 求 相 比 是 一 个 (或 多 个 ) 独立 的 新 请 求 ， 只 是 新 的 子 请 求 与 原 
台 请 求 之 间 可 以 并 发 的 处 理 。 














因此 ， 当 我 们 希望 把 第 三 方 服 务 的 内 容 几 乎 原封 不 动 地 返回 给 用 户 
时 ， 一 般 使 用 upstream 方 式 ， 它 可 以 非常 高 效 地 透 传 HITP【〈 第 12 章 详细 
描述 了 upstream 机 制 的 两 种 透 传 方式 ) 。 可 如 果 我 们 访问 第 三 方 服务 只 
是 为 了 获取 某 些 信息 ， 再 依据 这 些 信 息 来 构造 响应 并 发 送 给 用 户 ， 这 时 
应 该 用 subrequest 方 式 ， 因 为 从 业务 上 来 说 ， 这 是 两 件 事 : 获取 上 游 响 
应 ， 再 根据 响应 内 容 处 理 请 求 ， 应 由 两 个 请 求 处 理 。 




















本 章 仍 然 以 mytest 模 块 为 例 进 行 说 明 ， 但 会 扩展 mytest 的 功能 。 注 
意 ， 文 中 没有 提 及 的 代码 《〈 如 定义 mytest 模 块 ) 都 与 第 3 章 完全 相同 。 


5.1 _ upstream 的 使 用 方式 


Nginx 的 核心 功能 一 一 反 向 代理 是 基于 upstream 模 块 〈 该 模块 属于 
HTTP 框 染 的 一 部 分 〉 实 现 的 。 在 弄 清楚 upstream 的 用 法 后 ， 完 全 可 以 根 
据 目 己 的 需求 重 写 Nginx 的 反 回 代理 功能 。 例 如 ， 反 回 代 理 模块 是 在 先 
接收 完 客 户 请 求 的 HTTP 包 体 后 ， 才 同上 游 服务 器 建立 连接 并 转发 请 求 
的 。 假 设 用 户 要 上 传 大 小 为 1GB 的 文件 ， 由 于 网 速 限制 ， 文 件 完整 地 到 
达 Nginx 需 要 10 小 时 ， 恰 巧 Nginx 与 上 游 服 务 器 间 的 网 络 也 很 等 〈 当 然 这 
种 情况 很 少见 ) ， 反 回 代 理 这 个 请 求 到 上 游 服务 也 需要 10 小 时 ， 因 此 ， 
根据 用 户 的 网 速 也 许 本 来 只 要 10 个 小 时 的 上 传 过 程 ， 最 终 可 能 需要 20 个 
小 时 才能 完成 。 在 了 解 了 upstream 功 能 后 ， 可 以 试 着 改变 反 向 代理 模块 
的 这 种 特性 ， 比 如 模仿 squid 反 向 代理 模式 ， 在 接收 完整 HITP 请 求 的 头 
部 后 就 与 上 游 服务 器 建立 连接 ， 并 开始 将 请 求 同 上 游 服务 器 透 传 。 














upstream 的 使 用 方式 并 不 复杂 ， 它 提供 了 8 个 回调 方法 ， 用 户 只 需要 
视 上 自己 的 需要 实现 其 中 几 个 回调 方法 就 可 以 了 。 在 了 解 这 8 个 回调 方法 
之 前 ， 首 先 要 了 人 解 upstream 是 如 何 舱 入 到 一 个 请 求 中 的 。 








从 第 3 章 中 的 内 容 可 以 看 到 ， 模 块 在 处 理 任何 一 个 请 求 时 都 有 
ngx_http_request_t 结 构 的 对 象 r， 而 请 求 r 中 义 有 一 个 ngx_http_upstream_t 


类 型 的 成 员 upstream。 


typedef struct ngx_http_request_s ngx_http_request_t; 
struct ngx_http_request _s { 


ngx_http_upstream 七 *upstream; 





如 果 没 有 使 用 upstream 机 制 ， 那 么 ngx_http_request_t 中 的 upstream 成 
员 是 NULL 空 指针 ， 如 果 使 用 upstream 机 制 ， 那 么 关键 在 于 如 何 设置 r- 


>upstream 成 员 。 


图 5-1 列 出 了 使 用 HTTP 模 块 启 用 upstream 机 制 的 示意 图 。 下 面 以 
mytest 模 块 为 例 简 单 地 解释 一 下 图 5-1。 


1) 首先 需要 创建 上 面 介 绍 的 upstream 成 员 ， 注 意 ，upstream 在 初始 
状态 下 是 NULL 空 指针 。 可 以 调用 HTTP 框 架 提 供 好 的 
ngx_http_upstream_create 方 法 来 创建 upstream。 


2) 接着 设置 上 游 服 务 器 的 地 址 。 在 HTTP 反 向 代理 功能 中 似乎 只 能 
使 用 在 nginx.conf 中 配置 好 的 上 游 服务 器 《参见 2.5 节 的 upstream 配 置 块 
内 容 ) ， 而 实际 上 upstream 机 制 并 没有 这 种 要 求 ， 用 户 能 够 以 任意 方式 
指定 上 游 服务 器 的 耳 地 址 。 例 如 ， 可 以 从 请 求 的 URL 或 HITP 头 部 中 动 
态 地 获取 上 游 服 务 器 地 址 ，ngx_http_upstream t 中 的 resolved 成 员 就 可 以 
帮助 用 户 设置 上 游 服 务 器 《〈 详 见 5.1.3 节 ) 。 





3) 由 于 upstream 非 常 灵 活 ， 在 各 个 执行 阶段 中 都 会 试图 回调 使 用 它 
的 HITP 模 块 实现 的 8 个 方法 〈 详 见 5.1.4 节 ) ， 因 此 ， 在 mytest 模 块 例子 
中 ， 用 户 要 定义 好 这 些 回调 方法 。 


4) 在 mytest 模 块 中 ， 调 用 ngx_http_upstream_init 方 法 即 可 启动 
upstream 机 制 。 注 意 ，ngx_http_mytest_handler 方 法 此 时 必须 返回 
NGX_DONE， 这 是 在 要 求 HTTP 框 架 不 要 按 阶段 继续 向 下 处 理 请 求 了 ， 
同时 它 告诉 HTTP 框 染 请 求 必 须 保留 在 当前 阶段 ， 每 待 某 个 HTTP 模 块 主 
动 地 继续 处 理 这 个 请 求 〈 例 如 ， 在 上 游 服务 器 主动 关闭 连接 时 ， 
upstream 模 块 就 会 主动 地 继续 处 理 这 个 请 求 ， 很 可 能 会 同 客 户 端 发 送 502 
啊 应 码 ) 。 


出 用 ngx__http _upstream _create 方法 为 请 求 创建 upstream 


: 方 服务 带 的 地 址 


泣 用 ngx _http_upstream _init 方法 局 动 upstream 





图 5-1 启动 upstream 的 流程 图 


使 用 upstream 模 块 提 供 的 ngx_http_upstream_init 方 法 后 ，HTTP 框 架 
到 底 如 何 运行 upstream 机 制 呢 ? 图 5-2 给 出 了 一 个 常见 的 upstream 执 行 示 
意图 ， 它 仅 在 概念 上 表示 主要 流程 ， 与 代码 的 执行 没有 关系 。 第 12 章 将 

详细 介绍 upstream 机 制 到 底 是 如 何 执行 的 。 


图 5-2 所 示 的 upstream 流 程 包含 了 epol 恒 块 多 次 调度 、 处 理 一 个 请 求 
的 过 程 ， 它 虽然 与 实际 代码 执行 关系 不 大 ， 但 却 指出 了 最 常用 的 3 个 回 
调 方法 
的 。 


create_request、process_header、finalize_request 是 如 何 回调 























调 create _Teduest 方法 创建 发 往 上 游 的 请 求 


用 无 阻塞 套 接 字 建立 TCP 连 接 并 等 待 建立 成 功 


[ 等 待 上 游 服 务 器 的 SYN ACK 包 ] 


[TCP 连接 建立 成 功 ] 
发 送 请 求 到 第 三 方 服务 
[未 发 送 完 全 部 请 求 ] 
[发送 完全 部 请 求 ] 


接收 第 三 方 服务 返回 的 包头 


回调 process_header 方法 处 理 包 头 
[未 接收 到 完整 包头 ] 


[ 接收 到 完整 包头 ] 


处 理 第 三 方 服务 返回 的 包 体 
[ 上 游 服 务 器 还 在 发 送 包 体 ] 


<> 


[接收 、 处 理 完 全 部 的 包 体 ] 


调 finalize _request 并 销毁 请 求 





图 5-2 ”upstream 执 行 的 一 般 流 程 


人 @@ 注意 apsaeam 提 供 了 3 种 处 理 上 游 服 务 器 包 体 的 方式 ， 包 括 交 
由 HTTP 模 块 使 用 input_filter 回 调 方法 直接 处 理 包 体 、 以 固定 缓冲 区 转发 
包 体 、 以 多 个 缓冲 加 磁盘 文件 的 方式 转发 包 体 等 。 在 后 两 种 转发 包 体 的 
方式 中 ，upstream 还 与 文件 缓存 功能 紧密 相关 ， 但 为 了 让 大 家 更 清晰 地 


理解 upstteam， 本 章 中 将 不 涉及 文件 缓存 。 
5.1.1 ngx_http_upstream_t 结 构 体 


上 面 了 解 了 upstream 机 制 运行 的 主要 流程 ， 现 在 来 看 一 下 
ngx_http_upstream_t 结 构 体 。ngx_http_upstream_t 结 构 体 里 有 些 成 员 仅仅 
是 在 upstream 模 块 内 部 使 用 的 ， 这 里 就 不 一 一 列 出 了 《由 于 C 语 言 是 面 
向 过 程 语言 ， 所 以 ngx_http_upstream_t 结 构 体 里 会 出 现 第 三 方 HTTP 模 块 
并 不 关心 的 成 员 。 在 12.1.2 节 中 会 完整 地 介绍 ngx_http_upstream_t 中 的 所 





typedef struct ngx_http_upstream s ngx_http_upstream_t; 
struct ngx_http_upstream s { 

/*request_bufs 决 定 发 送 什 么 样 的 请 求 给 上 游 服 务 器 ， 在 实现 
create_request 方 法 时 需要 设置 它 


Ap 
ngx_chain *redquest_bufs 


// upstream 访 问 时 的 所 有 限制 性 参数 ， 在 


5.1.2 节 会 详细 讨论 它 


ngx_http_upstream conf_t *conf; 
// 通过 


resolved 可 以 直接 指定 上 游 服务 器 地 址 ， 在 


5.1.3 节 会 详细 讨论 它 


ngx_http_upstream_resolved t *resolved; 
/*buffer 成 员 存 储 接收 自 上 游 服 务 器 发 来 的 响应 内 容 ， 由 于 它 会 被 复 用 ， 所 以 具有 下 列 多 种 意义 : 


a) 在 使 用 


process_header 方 法 解析 上 游 响 应 的 包头 时 ， 


buffer 中 将 会 保存 完整 的 响应 包头 ; 


b) 当 下 面 的 


buffering 成 员 为 


1， 而 且 此 时 


Upstream 是 向 下 游 转发 上 游 的 包 体 时 ， 


buffer 没 有 意义 ; 


CcC) 当 


buffering 标 志 位 为 


0 时 ， 


buffer 缓 冲 区 会 被 用 于 反复 地 接收 上 游 的 包 体 ， 进 而 向 下 游 转 发 ; 


d) 当 


Upstream 并 不 用 于 转发 上 游 包 体 时 ， 


buffer 会 被 用 于 反复 接收 上 游 的 包 体 ， 


HTTP 模 块 实现 的 


input_filter 方 法 需要 关注 它 


*/ 
ngx_buf_t buffer ; 
// 构造 发 往 上 游 服务 器 的 请 求 内 容 


ngx_int_t (*create request)(ngx_http_request t *r); 
/* 收 到 上 游 服务 器 的 响应 后 就 会 回调 


process_header 方 法 。 如 果 


process_header 返 回 


NGX_AGAIN， 那 么 是 在 告诉 


Upstream 还 没有 收 到 完整 的 响应 包头 ， 此 时 ， 对 于 本 次 


Upstream 请 求 来 说 ， 再 次 接收 到 上 游 服 务 器 发 来 的 


TCP 流 时 ， 还 会 调用 


process_header 方 法 处 理 ， 直 到 


process_header 函 数 返回 非 


NGX_AGAIN 值 这 一 阶段 才 会 停止 


*/ 
ngx_int_t (*process header)(ngx_http_request t *r); 
// 销毁 


upstream 请 求 时 调用 


void (*finalize_request)(ngx_http_request 七 *r， 
ngx_int_t rc); 
// 5 个 可 选 的 回调 方法 


ngx_int_t (*input_filter_init)(void *data); 

ngx_int_t (*input_filter)(void *data, ssize t bytes); 

ngx_int_t (*reinit_request)(ngx_http_request _t *r); 

void (*abort_request)(ngx_http_request t *r); 

ngx_int_t (*rewrite redirect)(ngx_http_request t *r, 
ngx_table elt t *h, size t prefix); 

// 是 否 基 于 


SSL 协 议 访 问 上 游 服务 器 


unsigned ssl:1; 
/* 在 向 客户 端 转发 上 游 服 务 器 的 包 体 时 才 有 用 。 当 


buffering 为 

1 时 ， 表 示 使 用 多 个 缓冲 区 以 及 磁盘 文件 来 转发 上 游 的 响应 包 体 。 当 

Nginx 与 上 游 间 的 网 速 远大 于 

Nginx 与 下 游客 户 端 间 的 网 速 时 ， 让 

Nginx 开 辟 更 多 的 内 存 甚至 使 用 磁盘 文件 来 缓存 上 游 的 响应 包 体 ， 这 是 有 意义 的 ， 它 可 以 减轻 上 游 服务 器 的 并 发 压 
buffering 为 

旧时， 表示 只 使 用 上 面 的 这 一 个 

buffer 缓 冲 区 来 向 下 游 转发 响应 包 体 

*/ 


unsigned buffering:1; 


}; 





上 文 介绍 过 ，upstream 有 3 种 处 理 上 游 响 应 包 体 的 方式 ， 但 HTTP 模 
块 如 何 告诉 upstream 使 用 哪 一 种 方式 处 理 上 游 的 啊 应 包 体 呢 ? 当 请 求 的 


ngx_http_request_t 结 构 体 中 subrequest_in_memory 标 志 位 为 1 时 ， 将 采用 
第 1 种 方式 ， 即 upstream 不 转发 啊 应 包 体 到 下 游 ， 由 HTTP 模 块 实现 的 

input_filter 方 法 处 理 包 体 ;， 当 subrequest_in_memory 为 0 时 ，upstream 会 转 
发 响应 包 体 。 当 ngx_http_upstream_conf t 配 置 结构 体 中 的 buffering 标 志 
位 为 1 时 ， 将 开启 更 多 的 内 存 和 磁盘 文件 用 于 缓存 上 游 的 响应 包 体 ， 这 
意味 上 游 网 速 更 快 ， 当 buffering 为 0 时 ， 将 使 用 固定 大 小 的 缓冲 区 就 
是 上 面 介绍 的 buffer 绥 冲 区 〉 来 转发 啊 应 包 体 。 


@ 注意 ”上 述 的 8 个 回调 方法 中 ， 只 有 create_request、 





process_header、finalize_request 是 必须 实现 的 ， 其 余 5 个 回调 方法 
input_filter_init、input_filter、reinit_request、abotrt_request、 
rewtite_redirect 是 可 选 的 。 第 12 章 会 详细 介绍 如 何 使 用 这 5 个 可 选 的 回调 


方法 。 男 外 ， 这 8 个 方法 的 回调 场景 见 5.2 节 。 


5.1.2 ”设置 upstream 的 限制 性 参数 


本 节 介 绍 的 是 ngx_http_upstream_t 中 的 conf 成 员 ， 它 用 于 设置 
upstream 模 块 处 理 请 求 时 的 参数 ， 包 括 连接 、 发 送 、 接 收 的 超时 时 间 


要 
等 。 





typedef struct { 


// 连接 上 游 服务 器 的 超时 时 间 ， 单 位 为 毫秒 


ngx_msec connect_timeout; 
// 发 送 


TCP 包 到 上 游 服务 器 的 超时 时 间 ， 单 位 为 毫秒 


ngx_msec_t send_timeout,; 
// 接收 


TCP 包 到 上 游 服务 器 的 超时 时 间 ， 单 位 为 毫秒 


ngx_msec_t read_ timeout; 


} ngx_http_upstream conf_t; 





ngx_http_upstream_conf t 中 的 参数 有 很 多 ，12.1.3 节 会 完整 地 介绍 
所 有 成 员 。 事 实 上 ，HTTP 反 向 代理 模块 在 nginx.conf 文 件 中 提供 的 配置 
项 大 都 是 用 来 设置 ngx_http_upstream_conf_t 结 构 体 中 的 成 员 的 。 上 面 列 
出 的 3 个 超时 时 间 是 必须 要 设置 的 ， 因 为 它们 默认 为 0， 如 果 不 设 置 将 永 
远 无 法 与 上 游 服 务 器 建立 起 TCP 连 接 《〈 因 为 connect_timeout 值 为 0) 。 





使 用 第 4 章 介 绍 的 14 个 预 设 方法 可 以 非常 简单 地 通过 nginx.conf 配 置 
文件 设置 ngx_http_upstream_conf t 结 构 体 。 例 如 ， 可 以 把 
ngx_http_upstream_conf t 类 型 的 变量 放 到 ngx_http_mytest_conf t 结 构 体 
中 。 





typedef struct { 


ngx_http_upstream conf_t upstream; 
} ngx_http_mytest_conf_t; 











接 下 来 以 设置 connect_timeout 连 接 超时 时 间 为 例 说 明 如 何 编写 
ngx_command_t 来 读 取 配置 文件 。 





static ngx_command t ngx_http_mytest _ commands[] = {… 





{ ngx_string("upstream connect_ timeout"), 
NGX_HTTP_LOC_CONF |NGX_CONF_TAKE1, 
ngx_conf_set_msec_slot, 
NGX_HTTP_LOC_CONF_OFFSET， 

/* 给 出 








connect_timeout 成 员 在 


ngx_http_mytest_conf_t 结 构 体 中 的 偏 移 字 节 数 





*/ 
offsetof(ngx_http_mytest_conf_t, upstream.connect_timeout), 
NULL }, 








这 样 ，nginx.conf 文 件 中 的 upstream_conn_timeout 配 置 项 将 被 解析 到 
ngx_http_mytest_conf t 结 构 体 的 upstream.connect_timeout 成 员 中 。 在 处 
理 实际 请 求 时 ， 只 要 把 ngx_http_mytest_conf_t 配 置 项 的 upstream 成 员 赋 
给 ngx_http_upstream_t 中 的 conf 成 员 即 可 。 例 如 ， 在 
ngx_http_mytest_handler 方 法 中 可 以 这 样 设置 : 





ngx_http_mytest conf_t *mycf = (ngx_http mytest conf_t *) ngx_http_get module lorc 
r->upstream->conf = &mycf->upstream; 














上 面 代码 中 的 r>upstream->conf 是 必须 要 设置 的 ， 否 则 进程 会 裔 误 


(crash) 。 


罗 注意 ”每 一个 请 求 都 有 独立 的 negx_http_upsteam_conf t 结 构 
体 ， 这 意味 着 每 一 个 请 求 都 可 以 拥有 不 同 的 网 络 超时 时 间 等 配置 ， 用 户 
甚至 可 以 根据 HTTP 请 求 信息 决定 连接 上 游 服务 器 的 起 时 时 间 、 缓 存 上 
游 响 应 包 体 的 临时 文件 存放 位 置 等 ， 这 些 都 只 需要 在 设置 ->upstream- 
>conf 时 简单 地 进行 赋值 即 可 ， 有 时 这 非常 有 用 。 





5.1.3 ”设置 需要 访问 的 第 三 方 服务 器 地 址 


ngx_http_upstream_t 结 构 中 的 resolved 成 员 可 以 直接 设置 上 游 服 务 器 
的 地 址 。 首 先 介绍 一 下 resolved 的 类 型 。 





typedef struct { 


// 地 址 个 数 


ngx_uint_t naddrs ; 
// 上 游 服务 器 的 地 址 


struct sockaddr *sockaddr; 
socklen_t socklen; 


} ngx_http_upstream resolved t; 


ee | 


在 ngx_http_upstream_resolved_t 结 构 的 成 员 中 ， 必 须 设置 的 是 上 面 
代码 中 列 出 的 3 个 。 具 体 设 置 的 例子 可 参见 5.3 节 。 


当然 ， 还 有 其 他 方法 可 以 设置 上 游 服 务 嚣 地址 ， 感 兴趣 的 读者 可 以 
阅读 upstream 模 块 源 代码 ， 并 在 nginx.conf 文 件 中 配置 upstream 块 ， 指 定 
上 游 服 务 器 的 地 址 。 


5.1.4 设置 回调 方法 


5.1.1 节 介绍 的 ngx_http_upstream_t 结 构 体 中 有 8 个 回调 方法 ， 可 根据 
意义 实现 。 例 如 ，3 个 必须 实现 的 回调 方法 可 以 这 么 定义 : 





void mytest_upstream finalize request(ngx_http_request t *r, ngx_int _t rc); 
ngx_int_t mytest_upstream create _ request(ngx_http_request_t *r); 
ngx_int_t mytest_upstream process header(ngx_http_request t *r); 





在 5.3 节 中 ， 会 有 一 个 简单 的 例子 说 明 如 何 实现 上 述 3 个 方法 。 


然后 ， 在 ngx_http_mytest_handler 方 法 中 设置 它们 ， 例 如 : 





r->upstream->create_request = mytest_upstream create_ request,; 
r->upstream->process_header = mytest_process_status_line,; 
r->upstream->finalize_request=mytest_upstream finalize_request,; 





5.1.5 ”如 何 启 动 upstream 机 制 


直接 执行 hgx_http_upstream_init 方 法 即 可 启动 upstream 机 制 。 例 


如 : 


GS===== 二 = 二 二 = 


static ngx_int_t ngx_http_mytest_handler(ngx_http_request_t *r) 
{ 





r->main->count++; 
ngx_http_upstream init(r); 
return NGX_DONE,; 

} 





调用 ngx_http_upstream_init 就 是 在 启动 upstream 机 制 ， 这 时 要 通过 
返回 NGX_DONE 告 诉 HTTP 框 架 和 暂停 执行 请 求 的 下 一 个 阶段 。 这 里 还 需 
要 执行 ->main->count++， 这 是 在 告诉 HTTP 框 架 将 当前 请 求 的 引用 计数 
加 1， 即 告诉 ngx_http_mytest_handler 方 法 暂时 不 要 销毁 请 求 ， 因 为 
HTTP 框 架 只 有 在 引用 计数 为 O 时 才能 真正 地 销毁 请 求 。 这 样 的 话 ， 
upstream 机 制 接 下 来 才能 接管 请 求 的 处 理工 作 。 


@ 注意 “在 阅读 HTTP 反 向 代理 模块 (ngx_http_proxy_module) 源 
代码 时 ， 会 发 现 它 并 没有 调用 f->main->couht+ 十 ， 其 中 ptoxy 模 块 是 这 样 
启动 upstream 机 制 的 : 
ngx_http_read_client_request_body(t,nex_http_upstream_init);， 这 表示 读 取 
完 用 户 请 求 的 HTTP 包 体 后 才 会 调用 ngx_http_upstream_init 方 法 启动 
upstream 机 制 ( 参 见 3.6.4 节 ) 。 由 于 ngx_http_read_client_request_body 的 
第 一 行 有 效 语句 是 ft->main->count++， 所 以 HTTP 反 向 代理 模块 不 能 


次 在 其 代码 中 执行 fr->main->count+ 十 。 


这 个 过 程 看 起 来 似乎 让 人 困惑 。 为 什么 有 时 需要 把 引用 计数 加 1， 
有 时 却 不 需要 呢 ? 因 为 ngx_http_read_client_request_body 读 取 请 求 包 体 是 
一 个 异步 操作 (需要 epoll 多 次 调度 才能 完成 的 可 称 其 为 异步 操作 ) ， 
ngx_http_upstream_init 方 法 启用 upstream 机 制 也 是 一 个 异步 操作 ， 因 此 ， 
从 理论 上 来 说 ， 每 执行 一 次 异步 操作 应 该 把 引用 计数 加 1， 而 异步 操作 
结束 时 应 该 调用 npx_http_finalize_tequest 方 法 把 引用 计数 减 1。 另 外 ， 
ngx_http_read_client_request_body 方 法 内 是 加 过 引用 计数 的 ， 而 
ngx_http_upsttream_init 方 法 内 却 没有 加 过 引用 计数 (或 许 Nginx 将 来 会 修 
改 这 个 问题 ) 。 在 HTTP 反 向 代理 模块 中 ， 它 的 ngx_http_proxy_handler 方 
法 中 用 “ngx_http_read_client_request_body(r,ngx_http_upstream_init);” 语 
名 同时 启动 了 两 个 异步 操作 ， 注 意 ， 这 行 语句 中 只 加 了 一 次 引用 计数 。 
执行 这 行 语句 的 ngx_http_proxy_handlet 方 法 返回 时 只 调用 
ngx_http_finalize_request 方 法 一 次 ， 这 是 正确 的 。 对 于 mytest 模 块 也 一 
样 ， 务 必要 保证 对 引用 计数 的 增加 和 减少 是 配对 进行 的 。 


5.2 ”回调 方法 的 执行 场景 


使 用 upstream 方 式 时 最 重要 的 工作 都 会 在 回调 方法 中 实现 ， 为 了 更 
好 地 实现 它们 ， 本 市 将 介绍 调用 这 些 回 调 方法 的 典型 场景 。 


5.2.1 ”create_request 回 调 方 法 


create_request 的 回调 场景 最 简单 ， 即 它 只 可 能 被 调用 1 次 (如 果 不 
启用 upstream 的 失败 重 试 机 制 的 话 。 详 见 第 12 章 ) ， 如 图 5-3 所 示 。 下 面 
简单 地 介绍 一 下 图 5-3 中 的 每 一 个 步 又: 


1) 在 Nginx 主 循环 〈 这 里 的 主 循环 是 指 8.5 节 提 到 的 
ngx_worker_process_cycle 方 法 ) 中 ， 会 定期 地 调用 事件 模块 ， 以 检查 是 
舍 有 网 络 事件 发 生 。 


2) 事件 模块 在 接收 到 HTTP 请 求 后 会 调用 HTTP 框 染 来 处 理 。 假 设 
接收 、 解 析 完 HTTP 尖 部 后 发 现 应 该 由 mytest 模 块 处 理 ， 这 时 会 调用 
mytest 模 块 的 ngx_http_mytest_handler 来 处 理 。 





3) 这 里 mytest 模 块 此 时 会 完成 5.1.2 节 ~5.1.4 节 中 所 列 出 的 步骤 。 


4) 调用 ngx_http_upstream_init 方 法 启动 upstream。 
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7. 构造 完 待 发 证 下 
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9. 使 用 无 阻塞 大 楼 字 建立 TCP; 连接 






10. 无 阻塞 调用 返回 
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二 二 二 二 全 二 二 二 UL 
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图 5-3 ”cteate_tequest 回 调 场景 的 序列 图 





5) upstream 模 块 会 去 检查 文件 缓存 ， 如 果 绥 存 中 已 经 有 合适 的 啊 应 
包 ， 则 会 直接 返回 缓存 〈 当 然 必 须 是 在 使 用 反问 代理 文件 缓存 的 前 提 
) 。 为 了 让 读者 方便 地 理解 upstream 机 制 ， 本 章 将 不 再 提 及 文件 组 


存 。 
6) 回调 mytest 模 块 已 经 实现 的 create_request 回 调 方法 。 


7) mytest 模 块 通过 设置 r->upstream->request_bufs 已 经 决定 好 发 送 什 
么 样 的 请 求 到 上 游 服 务 器 。 


8) upstream 模 块 将 会 检查 5.1.3 节 中 介绍 过 的 resolved 成 员 ， 如 果 有 
resolved 成 员 的 话 ， 束 根据 它 设置 好 上 游 服 务 器 的 地 址 r->upstream->peer 
成 员 。 





9) 用 无 阻塞 的 TCP 套 接 字 建立 连接 。 


10) 无 论 连 接 是 否 建 立成 功 ， 负 责 建立 连接 的 connect 方 法 都 会 立刻 
返回 。 


11) ngx_http_upstream_init 运 回 。 
12) mytest 模 块 的 ngx_http_mytest_handler 方 法 返回 NGX_DONE。 


13) 当 事 件 模块 处 理 完 这 批 网 络 事件 后 ， 将 控制 权 交 还 给 Nginx 主 
循环 。 


5.2.2 ”reinit_request 回 调 方法 


reinit_request 可 能 会 被 多 次 回调 。 它 被 调用 的 原因 只 有 一 个 ， 就 是 
在 第 一 次 试图 同上 游 服 务 嚣 建 并 连接 时 ， 如 果 连 接 由 于 各 种 异常 原因 失 
败 ， 那 么 会 根据 upstream 中 conf 参 数 的 朱 略 要 求 再 次 草 连 上 游 服务 器 ， 
而 这 时 就 会 调用 reinit_request 方 法 了 。 图 5-4 描 述 了 典型 的 reinit request 
调用 场景 。 
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上 的 是 有 | 








| 
3. 设 置 request _sent 为 标志 位 1 
1 









| 
4 发 送 请 求 到 第 三 方 服务 


5. 无 阻塞 发 送 方法 返 





| 
6.TCP 连 接 建立 事件 处 理 完毕 


7. 本 次 网 络 事 件 处 理 完毕 












12 .检查 request_sent 时 发 现 已 经 为 1 


13. 回调 reinit__ request 


14. 回调 方法 执行 完毕 
一 方 


15.TCP 连接 断 开 事件 处 理 完 毕 
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图 5-4 teinit_fequest 回 调 场景 的 序列 图 


下 面 简单 地 介绍 一 下 图 5-4 中 列 出 的 步骤 。 





1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事件 发 
2 


2) 事件 模块 在 确定 与 上 游 服 务 器 的 TCP 连 接 建 立成 功 后 ， 会 回调 
upstream 模 块 的 相关 方法 处 理 。 


3) upstream 模 块 这 时 会 把 r->upstream->request_sent 标 志 位 置 为 1， 
表示 连接 已 经 建立 成 功 了 ， 现 在 开始 向 上 游 服务 器 发 送 请 求 内 容 。 


4) 发 送 请 求 到 上 游 服务 器 。 





5) 发 送 方法 当然 是 无 阻 守 的 《使 用 了 无 阻塞 的 套 接 字 ) ， 会 立刻 
返回 。 


6) upstream 模 块 处 理 第 2 步 中 的 TCP 连 接 建立 成 功 事件 。 


7) 事件 模块 处 理 完 本 轮 网 络 事件 后 ， 将 控制 权 交 还 给 Nginx 主 循 
环 。 


8) Nginx 主 循环 重复 第 1 步 ， 调 用 事件 模块 检查 网 络 事件 。 


) 这 时 ， 如 果 发 现 与 上 游 服务 器 建立 的 TCP 连 接 已 经 异常 断 开 ， 
那么 事件 模块 会 通知 upstream 模 块 处 理 它 。 


10) 在 符合 重 试 次 数 的 前 提 下 ，upstream 模 块 会 训 不 犹 殉 地 再 次 用 
无 阻塞 的 套 接 字 试图 建立 连接 。 


11) 无 论 连接 是 售 建 立成 功 都 立刻 返回 。 


12) 这 时 检查 r->upstream->request_sent 标 志 位 ， 会 发 现 它 已 经 被 置 


为 1 了 。 


13) 如 果 mytest 模 块 没 有 实现 reinit_request 方 法 ， 那 么 是 不 会 调用 它 
的 。 而 如 果 reinit_request 不 为 NULL 空 指针 ， 就 会 回调 它 。 


14) mytest 模 块 在 reinit_request 中 处 理 完 自己 的 事情 。 





15) 处 理 完 第 9 步 中 的 TCP 连 接 断 开 事 件 ， 将 控制 权 交 还 给 事件 模 
块 。 


16) 事件 模块 处 理 完 本 轮 网 络 事件 后 ， 交 还 控制 权 给 Nginx 主 循 
环 。 


5.2.3 finalize_request 回 调 方法 


当 调 用 ngx_http_upstream_init 启 动 upstream 机 制 后 ， 在 各 种 原 
《无论 成 功 还 是 失败 ) 导致 该 请 求 被 销毁 前 都 会 调用 finalize_request 方 
法 (参见 图 5-1) 。 


在 finalize_request 方 法 中 可 以 不 做 任何 事情 ， 但 必须 实现 
finalize_request 方 法 ， 否 则 Nginx 会 出 现 空 指针 调用 的 严重 错误 。 


5.2.4 ”process_header 回 调 方 法 


process_header 是 用 于 解析 上 游 服 务 器 返回 的 基于 TCP 的 啊 应 头 部 
的 ， 因 此 ，process_header 可 能 会 被 多 次 调用 ， 它 的 调用 次 数 与 
process_header 的 返回 值 有 关 。 如 图 5-5 所 示 ， 如 果 process_header 返 回 
NGX_AGAIN， 这 意味 着 还 没有 接收 到 完整 的 啊 应 头 部 ， 如 有 果 再 次 接收 
到 上 游 服务 器 发 来 的 TCP 流 ， 还 会 把 它 当 做 头 部 ， 仍 然 调用 
process_header 处 理 。 而 在 图 5-6 中 ， 如 果 process_header 返 回 
NGX_OK (或 者 其 他 非 NGX_AGAIN 的 值 ) ， 那 么 在 这 次 连接 的 后 续 处 
理 中 将 不 会 再 次 调用 process_header。 
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8. 再 次 读 取 套 接 字 1 


9. 返 回 套 接 字 缓存 区 中 没有 的 内 容 
et | 


| 
| | 
11. 本 次 网 络 事件 处 理 完毕 


图 5-5 ”ptocess_headet 回 调 场景 的 序列 图 


下 面 简单 地 介绍 一 下 图 5-5 中 列 出 的 步 又 。 





1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事件 发 
2 


2) 事件 模块 接收 到 上 游 服 务 器 发 来 的 啊 应 时 ， 会 回调 upstream 模 块 
处 理 。 


3) upstream 模 块 这 时 可 以 从 套 接 字 绥 冲 区 中 读 取 到 来 自 上 游 的 TCP 





4) 读 取 的 响应 会 存放 到 r->upstream->buffer 指 向 的 内 存 中 。 注 意 : 
在 未 解析 完 响 应 头 部 前 ， 知 多 次 接收 到 字符 流 ， 所 有 接收 自 上 游 的 啊 应 
都 会 完整 地 存放 到 r->upstream->buffer 绥 冲 区 中 。 因 此 ， 在 解析 上 游 响 
应 包头 时 ， 如 果 buffer 缓 冲 区 全 满 却 还 没有 解析 到 完整 的 响应 头 部 《也 
就 是 说 ，process_header 一 直 在 返回 NGX_AGAIN) ， 那 么 请 求 就 会 出 
错 。 





5) 调用 mytest 模 块 实现 的 process_header 方 法 。 


6) process_header 方 法 实际 上 就 是 在 解析 r->upstream->buffer 绥 冲 
区 ， 试 图 从 中 取 到 完整 的 啊 应 头 部 (当然 ， 如 果 上 游 服 务 器 与 Nginx 通 
过 HTTP 通 信 ， 就 是 接收 到 完整 的 HITP 头 部 ) 。 


7) 如 果 process_header 返 回 NGX_AGAIN， 那 么 表示 还 没有 解析 到 
完整 的 响应 头 部 ， 下 次 还 会 调用 process_header 处 理 接收 到 的 上 游 响 应 。 





8) 调用 无 阻 窄 的 读 取 僚 接 字 接 口 。 


9) 这 时 有 可 能 返回 套 接 字 缓 冲 区 已 经 为 空 。 





10) 当 第 2 步 中 的 读 取 上 游 啊 应 事件 处 理 完毕 后 ， 控 制 权 交还 给 事 
件 模块 。 


11) 事件 模块 处 理 完 本 轮 网 络 事件 后 ， 交 还 控制 权 给 Nginx 主 循 
环 。 


5.2.5 ”rewrite_redirect 回 调 方 法 


在 重 定向 URL 阶 段 ， 如 果实 现 了 rewrite_redirect 回 调 方 法 ， 那 么 这 

时 会 调用 rewrite_redirect。 注 意 ， 本 章 不 涉及 rewrite_redirect 方 法 ， 感 兴 
趣 的 读者 可 以 查看 upstream 模 块 的 ngx_http_upstream_rewrite_location 方 
法 。 如 果 upstream 模 块 接收 到 完整 的 上 游 响 应 头 部 ， 而 且 由 HTTP 模 块 的 
process_header 回 调 方法 将 解析 出 的 对 应 于 Location 的 头 部 设置 到 了 
ngx_http_upstream_t 中 的 headers_in 成 员 时 ， 
ngx_http_upstream_process_headers 方 法 将 会 最 终 调用 rewrite_redirect 方 法 

《 见 12.5.3 节 图 12-5 的 第 8 步 ) 。 因 此 ，rewrite_redirect 的 使 用 场景 比较 
少 ， 它 主要 应 用 于 HTTP 反 辣 代 理 模 块 (ngx_http_proxy_module) 。 


5.2.6 ”input_filter_init 与 input_filter 回 调 方 法 


input_filter_init 与 input_filter 这 两 个 方法 都 用 于 处 理 上 游 的 响应 包 
体 ， 因 为 处 理 包 体 前 HTTP 模 块 可 能 需要 做 一 些 初 始 化 工作 。 例 如 ， 分 


配 一 些 内 存 用 于 存放 解析 的 中 间 状 态 等 ， 这 时 upstream 惑 提供 了 
input_filter_init 方 法 。 而 input_filter 方 法 就 是 实际 处 理 包 体 的 方法 。 这 两 
个 回调 方法 都 可 以 选择 不 予 实现 ， 这 是 因为 当 这 两 个 方法 不 实现 时 ， 
upstream 模 块 会 自动 设置 它们 为 预 置 方 法 (上 文 讲 过 ， 由 于 upstream 有 3 
种 处 理 包 体 的 方式 ， 所 以 upstream 模 块 准备 了 3 对 input_filter_init、 
input_filter 方 法 ) 。 因 此 ， 一旦 试图 重 定义 input_filter_init、input_filter 
方法 ， 就 意味 着 我 们 对 upstream 模 块 的 默认 实现 是 不 满意 的 ， 所 以 才 要 
重 定义 该 功能 。 此 时 ， 前 先 必须 要 弄 清楚 默认 的 input_filter 方 法 到 底 做 
了 什么 ， 在 12.6 节 ~12.8 节 介绍 的 3 种 处 理 包 体 方 式 中 ， 都 会 涉及 默认 的 
input_filter 方 法 所 做 的 工作 。 














在 多 数 情况 下 ， 会 在 以 下 场景 决定 重新 实现 input_filter 方 法 。 
(1) 在 转发 上 游 啊 应 到 下 游 的 同时 ， 需 要 做 一 些 特殊 人 处理 


例如 ，ngx_http_memcached_module 模 块 会 将 实际 由 memcached 实 现 
的 上 游 服务 器 返回 的 响应 包 体 ， 转 发 到 下 游 的 HTTP 客户 端 上 。 在 上 述 
过 程 中 ， 该 模块 通过 重 定义 了 的 input_filter 方 法 来 检测 memcached 协 议 
下 包 体 的 结束 ， 而 不 是 完全 、 纯 粹 地 透 传 TCP 流 。 





(2) 当 无 须 在 上 、 下 洲 间 转发 啊 应 时 ， 并 不 想 等 竺 接收 完全 部 的 
上 游 啊 应 后 才 开始 处 理 请 求 





在 不 转发 啊 应 时 ， 通 常会 将 响应 包 体 存放 在 内 存 中 解析 ， 如 果 试 图 








接收 到 完整 的 啊 应 后 再 来 解析 ， 由 于 啊 应 可 能 会 非常 大 ， 这 会 占用 大 量 
内 存 。 而 重 定 义 了 input_filter 方 法 后 ， 可 以 每 解析 完 一 部 分 包 体 ， 就 释 
放 一 些 内 存 。 


重 定义 input_filter 方 法 必须 符合 一 些 规 则 ， 如 怎样 取 到 刚 接收 到 的 
包 体 以 及 如 何 释 放 绥 冲 区 使 得 固定 大 小 的 内 存 缓冲 区 可 以 重复 使 用 等 。 
注意 ， 本 章 的 例子 并 不 涉及 input_filter 方 法 ， 读 者 可 以 在 第 12 章 中 找到 
input_filter 方 法 的 使 用 方式 。 


5.3 ”使 用 upstream 的 示例 


下 面 以 一 个 简单 且 能 够 运行 的 示例 帮助 读者 理解 如 何 使 用 upstream 
机 制 。 这 个 示例 要 实现 的 功能 很 简单 ， 即 以 访问 mytest 模 块 的 URL 参 数 
作为 搜索 引擎 的 关键 字 ， 用 upstream 方 式 访问 google， 查 询 URL 里 的 参 
数 ， 然 后 把 google 的 结果 返回 给 用 户 。 这 个 场景 非常 适合 使 用 upstream 
方式 ， 因 为 Nginx 访 问 google 的 服务 堪 使 用 的 是 HITP， 它 当然 符合 
upstream 的 使 用 场景 : 上 游 服 务 器 提供 基于 TCP 的 协议 。 上 文 讲 过 ， 
upstream 提 供 了 3 种 处 理 包 体 的 方式 ， 这 里 选择 以 固定 缓冲 区 向 下 游客 户 
端 转发 google 返 回 的 包 体 HTTP 的 包 体 )〉 的 方式 。 


例如 ， 如 果 访 问 的 URL 是 /test?lumia， 那 么 在 nginx.conf 中 可 以 这 样 
配置 location。 





location /test { 
mytest; 





mytest 模 块 将 会 使 用 upstream 机 制 同 www.google.com 发 送 搜索 请 
求 ， 它 的 请 求 URL 是 /search?q=lumia，google 返 回 的 包头 将 在 mytest 模 块 
中 解析 并 决定 如 何 转发 给 用 户 ， 而 包 体 将 会 被 透 传 给 用 户 。 


这 里 继续 以 mytest 模 块 为 例 来 说 明 如 何 使 用 upstream 达 成 上 述 效 


果 。 
5.3.1 “upstream 的 各 种 配置 参数 


每 一 个 HTTP 请 求 都 会 有 独立 的 ngx_http_upstream_conf t 结 构 体 ， 
出 于 简单 考虑 ， 在 mytest 模 块 的 例子 中 ， 所 有 的 请 求 都 将 共享 同一 个 
ngx_http_upstream_conf t 结 构 体 ， 因 此 ， 这 里 把 它 放 到 
ngx_http_mytest_conf _t 配 置 结构 体 中 ， 如 下 所 示 。 





typedef struct { 
ngx_http_upstream conf_t upstream; 
} ngx_http_mytest_conf_t,; 








在 启动 upstream 前 ， 先 将 ngx_http_mytest_conf_t 下 的 upstream 成 员 赋 


给 r->upstream->conf 成 员 ， 可 参考 5.3.6 节 中 的 示例 代码 。 


ngx_http_upstream_conf {t 结 构 中 的 各 成 员 可 以 通过 第 4 章 中 介绍 的 
方法 ， 即 用 预 设 的 配置 项 解析 参数 来 赋值 ， 如 5.1.2 市 中 的 例子 所 示 。 出 
于 方便 ， 这 里 直接 硬 编 码 到 create_loc_conf 回 调 方法 中 了 ， 如 下 所 示 。 





static void* ngx_http_mytest_create_loc conf(ngx_conf_t *cf) 


‘ 





ngx_http_mytest_conf t *mycf; 
mycf = (ngx_http_mytest_conf t *)ngx_pcalloc(cf->pool, sizeof(ngx_http_mytest_c 
if (mycf == NULL) { 








return NULL; 


} 
/* 以 下 简单 的 硬 编码 


ngx_http_upstream_conf_t 结 构 中 的 各 成 员 ， 如 超时 时 间 ， 都 设 为 


1 分 钟 ， 这 也 是 


HTTP 反 向 代理 模块 的 默认 值 


2 
mycf->upstream.connect_timeout = 60000; 
mycf->upstream.send_timeout = 60000; 
mycf->upstream.read_timeout = 60000 
mycf->upstream.store_access = 0600; 
/* 实 际 上 ， 


由 | | 


buffering 己 经 决定 了 将 以 固定 大 小 的 内 存 作为 缓冲 区 来 转发 上 游 的 响应 包 体 ， 这 块 国定 缓冲 区 的 大 小 就 是 


buffer_size。 如 果 


buffering 为 


1， 就 会 使 用 更 多 的 内 存 缓存 来 不 及 发 往 下 游 的 响应 。 例 如 ， 最 多 使 用 


bufs .num 个 缓冲 区 且 每 个 缓冲 区 大 小 为 


bufs .Size。 另 外 ， 还 会 使 用 临时 文件 ， 临 时 文件 的 最 大 长 度 为 


max_temp_file size*/ 
mycf->upstream.buffering = 0; 
mycf->upstream,bufs ,num = 8; 
mycf->upstream.bufs.size = ngx_pagesize; 
mycf->upstream.buffer_size = ngx_pagesize; 
mycf->upstream.busy_buffers_size = 2*ngx_pagesize,; 
mycf->upstream.temp_file write size = 2 * ngx_pagesize,; 
mycf->upstream.max_temp_file_ size = 1024 * 1024 * 1024; 
/*Upstream 模 块 要 求 


hide_headers 成 员 必 须要 初始 化 ( 


Upstream 在 解析 完 上 游 服 务 器 返回 的 包头 时 ， 会 调用 


ngx_http_upstream_process_headers 方 法 按照 


hide_headers 成 员 将 本 应 转发 给 下 游 的 一 些 


HTTP 头 部 隐藏 ) ， 这 里 将 它 赋 为 


NGX_CONF_UNSET_PTR ， 这 是 为 了 在 


merge 合 并 配置 项 方法 中 使 用 


UpSstream 模 块 提供 的 


ngx_http_upstream_hide_headers_hash 方 法 初始 化 


hide_headers 成 员 


*/ 
mycf->upstream.hide_ headers = NGX_ CONF_UNSET_PTR; 
mycf->upstream.pass_headers = NGX_CONF_UNSET_PTR; 
return mycf; 

} 





hide_headers 的 类 型 是 ngx_array_t 动 态 数组 (实际 上 ，upstream 模 块 
将 会 通过 hide_headers 来 构造 hide_headers_hash 散 列表 ) 。 由 于 upstream 
模块 要 求 hide_headers 不 可 以 为 NULL， 所 以 必须 要 初始 化 hide_headers 
成 员 。upstream 模 块 提供 了 ngx_http_upstream_hide_headers_hash 方 法 来 
初始 化 hide_headers， 但 仅 可 用 在 合并 配置 项 方法 内 。 例 如 ， 在 下 面 的 
ngx_http_mytest_merge_loc_conf 方 法 中 就 可 以 使 用 ， 如 下 所 示 ， 








static char *ngx_http_mytest_ merge_ loc conf(ngx_conf_t *cf, void *parent, void *chi] 
{ 

ngx_http_mytest_conf_t *prev = (ngx_http_mytest_conf_t *)parent,; 

ngx_http_mytest_conf_t *conf = (ngx_http_mytest_ conf_t *)child; 

ngx_hash_init_t hash ， 

hash.max_size = 100; 

hash.bucket_size = 1024; 

hash.name = "proxy_headers_hash"; 

If (ngx_http_upstream hide_ headers hash(cf, &conf->upstream, 

&prev->upstream, ngx_http_proxy_hide_ headers, &hash) 
!= NGX_OK) 

















return NGX_CONF_ERROR; 


return NGX_CONF_OK, 


53.2 -便于 上 下 议 


本 节 介 绍 的 例子 就 必须 要 使 用 上 下 文才 能 正确 地 解析 upstream 上游 
服务 器 的 响应 包 ， 因 为 upstream 模 块 每 次 接收 到 一 段 TCP 流 时 都 会 回调 
mytest 模 块 实现 的 process_header 方 法 解析 ， 这 样 就 需要 有 一 个 上 下 文保 
存 解析 状态 。 在 解析 HTTP 啊 应 行 时 ， 可 以 使 用 HTTP 框 染 提 供 的 
ngx_http_status_t 结 构 ， 如 下 所 示 。 








typedef struct { 


ngx_uint_t code; 
ngx_uint_t count; 
u_char *start,; 
u_char *end; 


} ngx_http_status_t; 





把 ngx_http_status_t 结 构 放 到 上 下 文中 ， 并 在 process_header 解 析 咯 
应 行 时 使 用 ， 如 下 所 示 。 





typedef struct { 
ngx_http_status_t status; 
} ngx_http_mytest_ctx_t; 








在 5.3.4 节 实现 process_header 的 代码 中 ， 可 以 学 会 如 何 使 用 


ngx_http_status_t 结 构 。 


5.3.3 ”在 create_request 方 法 中 构造 请 求 


这 里 定义 的 mytest_upstream_create_request 方 法 用 于 创建 发 送 给 上 游 


服务 器 的 HTTP 请 求 ，upstream 模 块 将 会 回调 它 ， 实 现 如 下 。 





static ngx_int_t 

mytest_upstream create _ request(ngx_http_request_t *r) 
/* 发 往 

9g00gle 上 游 服 务 器 的 请 求 很 简单 ， 就 是 模仿 正常 的 搜索 请 求 ， 以 

/Searchq=… 的 

URL 来 发 起 搜索 请 求 。 

backendQueryLine 中 的 

%V 等 转化 格式 的 用 法 ， 可 参见 表 


4-7*/ 
static ngx_str_t backendQueryLine = 
ngx_string("GET /searchq=%V HTTP/1.1\r\nHost: www.google.com\r\nCc 
ngx_int_t queryLineLen = backendQueryLine.len + r->args.len - 2; 
/* 必 须 在 内 存 池 中 申请 内 存 ， 这 有 以 下 两 点 好 处 : 一 个 好 处 是 ， 在 网 络 情况 不 佳 的 情况 下 ， 向 上 游 服 务 器 发 送 


epol1 多 次 调度 


Send 才 能 发 送 完成 ， 这 时 必须 保证 这 段 内 存 不 会 被 释放 ; 另 一 个 好 处 是 ， 在 请 求 结束 时 ， 这 段 内 存 会 被 自动 释放 ， 


4 
ngx_buf_t* b = ngx_create temp_buf(r->pool, queryLineLen); 
if (b == NULL) 
return NGX_ERROR,; 
// last 要 指向 请 求 的 末尾 


b->last = b->pos + queryLineLen; 
// 作用 相当 于 


snprintf， 只 是 它 支持 表 


4-7 中 列 出 的 所 有 转换 格式 


ngx_snprintf(b->pos, queryLineLen ， 
(char*)backendQueryLine.data, &r->args); 
/* r->upstream->request_bufs 是 一 个 


ngx_chain_t 结 构 ， 它 包含 着 要 发 送 给 上 游 服务 器 的 请 求 


4 
r->upstream->request_bufs = ngx_alloc chain_link(r->pool); 
if (r->upstream->request_bufs == NULL) 
return NGX_ERROR,; 
// request_bufs 在 这 里 只 包含 


人 


ngx_buf t 缓 冲 区 


r->upstream->request_bufs->buf = b， 
r->upstream->request_bufs->next = NULL 
r->upstream->request_sent = 0; 
r->upstream->header_sent = 0; 

// header_hash 不 可 以 为 


r->header_hash = 1; 
return NGX_OK; 





5.3.4 在 process_header 方 法 中 解析 包头 





process_header 负 责 解 析 上 游 服 务 器 发 来 的 基于 TCP 的 包头 ， 在 本 例 
中 ， 就 是 解析 HTTP 响 应 行 和 HTTP 头 部 ， 因 此 ， 这 里 使 用 
mytest_process_status_line 方 法 解析 HTTP 响 应 行 ， 使 用 
mytest_Uupstream_process_header 方 法 解析 http 啊 应 头 部 。 之 所 以 使 用 两 个 
方法 解析 包头 ， 这 也 是 HTTP 的 复杂 性 造成 的 ， 因 为 无 论 是 啊 应 行 还 是 
啊 应 头 部 都 是 不 定 长 的 ， 都 需要 使 用 状态 机 来 解析 。 实 际 上 ， 这 两 个 方 
法 也 是 通用 的 ， 它 们 适用 于 解析 所 有 的 HTTP 啊 应 包 ， 而 且 这 两 个 方法 
的 代码 与 ngx_http_proxy_module 模 块 的 实现 几乎 是 完全 一 致 的 。 








static ngx_int_ 
mytest_process_status_line(ngx_http_request_t *r) 
{ 

size_t len; 

ngx_int_t re; 

ngx_http_upstream t *U; 

// 上 下 文中 才 会 保存 多 次 解析 


HTTP 响 应 行 的 状态 ， 下 面 首先 取出 请 求 的 上 下 文 


ngx_http_mytest_ctx_t* ctx = ngx_http_get module ctx(r,ngx_http_mytest_module); 
If (ctx == NULL) { 
return NGX_ERROR; 








} 
U = r->upstream,; 
/*HTTP 框 架 提供 的 


ngx_http_parse_status_line 方 法 可 以 解析 





HTTP 响 应 行 ， 它 的 输入 就 是 收 到 的 字符 流 和 上 下 文中 的 
ngx_http_status_t 结 构 


*/ 
rc = ngx_http_parse_status line(r, &u->buffer, &ctx->status); 
// 返回 





NGX_AGAIN 时 ， 表 示 还 没有 解析 出 完整 的 


HTTP 响 应 行 ， 需 要 接收 更 多 的 字符 流 再 进行 解析 


4 
if (rc == NGX_AGAIN) { 
return rc; 


// 返回 


NGX_ERROR 时 ， 表 示 没 有 接收 到 合法 的 


HTTP 响 应 行 


if (rc == NGX_ERROR) { 
ngx_log_error(NGX_LOG_ERR, r->connection->log, 0, 
"upstream sent no valid HTTP/1.0 header"); 
r->http_version = NGX_HTTP_VERSION_9; 
uU->state->status = NGX_HTTP_OK; 


return NGX_OK; 


J 
HTTP 响 应 行 时 ， 会 做 一 些 简单 的 赋值 操作 ， 将 解析 出 的 信息 设置 到 
r->upstream->headers_in 结 构 体 中 。 当 
upstream 解 析 完 所 有 的 包头 时 ， 会 把 
headers_in 中 的 成 员 设 置 到 将 要 向 下 游 发 送 的 
r->headers_out 结 构 体 中 ， 也 就 是 说 ， 现 在 用 户 向 
headers_in 中 设置 的 信息 ， 最 终 都 会 发 往 下 游客 户 端 。 为 什么 不 直接 设置 


r->headers_out 而 要 多 此 一 举 呢 ? 因为 





Upstream 和 希望 能 够 按照 
ngx_http_upstream_conf_t 配 置 结构 体 中 的 
hide_headers 等 成 员 对 发 往 下 游 的 响应 头 部 做 统一 处 理 


Wy 
If (u->state) { 
u->state->status = ctx->status.code,; 
} 


u->headers_in,.status_n = ctx->status.code; 
len = ctx->status.end - ctx->status.start,; 
uU->headers_in.status_line.len = len,; 
Uu->headers_in.status_line.data = ngx_pnalloc(r->pool, len); 
If (u->headers_in.status line.data == NULL) { 
return NGX_ERROR 

} 
ngx_memcpy(u->headers_in,.status_ line.data, ctx->status.start, len); 
/* 下 一 步 将 开始 解析 

HTTP 头 部 。 设 置 

process_header 回 调 方法 为 


mytest_upstream_process_header， 之 后 再 收 到 的 新 字符 流 将 由 


mytest_upstream_process_header 解 析 


*/ 
U->process_header = mytest_upstream process_ header; 
/* 如 果 本 次 收 到 的 字符 流 除 了 


HTTP 响 应 行 外 ， 还 有 多 余 的 字符 ， 那 么 将 由 


mytest_upstream_process_header 方 法 解析 


0 


} 


return mytest_upstream process_header(r); 





mytest_upstream_process_header 方 法 可 以 解析 HTTP 啊 应 头 部 ， 而 这 
个 例子 只 是 简单 地 把 上 游 服 务 器 发 送 的 HITP 头 部 添加 到 了 请 求 r- 
>upstream->headers_in.headers 链 表 中 。 如 果 有 需要 特殊 处 理 的 HITP 头 
部 ， 那 么 也 应 该 在 mytest_upstream_process_header 方 法 中 进行 。 





static ngx_int_t 
mytest_upstream process_ header(ngx_http_request _t *r) 


ngx_int_t re; 
ngx_table elt_t *h; 
ngx_http_upstream header_t *hh; 
ngx_http_upstream main_conf_t *umcf， 
/* 这 里 将 

Upstream 模 块 配置 项 


ngx_http_upstream_main_conf t 取 出来， 目的 只 有 一 个 ， 就 是 对 将 要 转发 给 下 游客 户 端的 


HTTP 响 应 头 部 进行 统一 处 理 。 该 结构 体 中 存储 了 需要 进行 统一 处 理 的 


HTTP 头 部 名 称 和 回调 方法 


*/ 
umcf = ngx_http_get_module main_conf(r, ngx_http_upstream module); 
// 循环 地 解析 所 有 的 





HTTP 头 部 


for (7 ) 1 
/* HTTP 框 架 提供 了 基础 性 的 


ngx_http_parse_header_line 方 法 ， 它 用 于 解析 





HTTP 头 部 


2 
rc = ngx_http_parse_header_ line(r, &r->upstream->buffer, 1); 
// 返回 





NGX_OK 时 ， 表 示 解 析出 一 行 


HTTP 头 部 


If (rc == NGX_OK) { 
// 向 


headers_in.headers 这 个 


ngx_1list_t 链 表 中 添加 


HTTP 头 部 
h = ngx_list_push(&r->upstream->headers_in.headers); 
if (h == NULL) { 
return NGX_ERROR,; 
} 
// 下 面 开 始 构造 刚刚 添加 到 
headers 链 表 中 的 
HTTP 头 部 


h->hash = r->header_hash 

h->key.len = r->header_name_end - r->header_ name_start,; 
h->value.len = r->header_end - r->header_start; 

// 必须 在 内 存 池 中 分 配 存放 


HTTP 头 部 的 内 存 空间 


h->key.data = ngx_pnalloc(r->pool, 
h->key.len + 1 + h->value.len + 1 + h->key.1en); 
if (h->key.data == NULL) { 
return NGX_ERROR,; 
} 


h->value.data = h->key.data + h->key.len + 1; 

h->lowcase_key = h->key.data + h->key.len + 1 + h->value.len + 1; 
ngx_memcpy(h->key.data, r->header name_start, h->key.1en); 
h->key.data[h->key.len] = '\0'，; 

ngx_memcpy(h->value.data, r->header_start, h->value.1len); 


h->value.data[h->value.len] = '\0'; 

If (h->key.len == r->lowcase_index) { 
ngx_memcpy(h->lowcase_key, r->lowcase_ header, h->key.1en); 

} else { 


ngx_strlow(h->lowcase_key, h->key.data, h->key.1len); 


} 
// _ Upstream 模块 会 对 一 些 


HTTP 头 部 做 特殊 处 理 


hh = ngx_hash_find(&umcf->headers_in_hash, h->hash, 
h->lowcase_key, h->key.1en); 
if (hh && hh->handler(r, h, hh->offset) != NGX _ OK) { 
return NGX_ERROR ， 
} 四 
continue; 


} 
/* 返 回 


NGX_HTTP_PARSE_HEADER_DONE 时 ， 表 示 响 应 中 所 有 的 





HTTP 头 部 都 解析 完毕 ， 接 下 来 再 接收 到 的 都 将 是 


HTTP 包 体 


*/ 
if (rc == NGX_HTTP_PARSE_ HEADER DONE) { 
/* 如 果 之 前 解析 





HTTP 头 部 时 没有 发 现 


server 和 


date 头 部 ， 那 么 下 面 会 根据 


HTTP 协 议 规范 添加 这 两 个 头 部 


*/ 
if (r->upstream->headers_ in,server == NULL) { 


h = ngx_list_push(&r->upstream->headers_in.headers); 
if (h == NULL) { 
return NGX_ERROR, 


} 
h->hash = ngx_hash(ngx_hash(ngx_hash(ngx_hash( 
ngx hash( Sty ary ‘ry, wy ey MY 
ngx_str_set(&h->key, "Server"); 
ngx_str_null(&h->value); 
h->lowcase_key = (u_char *) "server",; 


if (r->upstream->headers in,.date == NULL) { 
h = ngx_list_push(&r->upstream->headers_in.headers); 
if (h == NULL) { 
return NGX_ERROR, 
} 
h->hash = ngx_hash(ngx_hash(ngx_hash('d', 'a'), 't'), 'e'); 
ngx_str_set(&h->key, "Date"); 
ngx_str_null(&h->value); 
h->lowcase_key = (u_char *) "date"; 
} 
return NGX_OK; 


/* 如 果 返 回 
NGX_AGAIN， 则 表示 状态 机 还 没有 解析 到 完整 的 
HTTP 头 部 ， 此 时 要 求 
Upstream 模 块 继续 接收 新 的 字符 流 ， 然 后 交 由 


process_header 回 调 方法 解析 


* 

if (rc == NGX_AGAIN) { 
return NGX_AGAIN 
// 其 他 返回 值 都 是 非法 的 
ngx_log_error(NGX_LOG_ERR, r->connection->log, 0, 
"upstream sent invalid header"); 
return NGX_HTTP_UPSTREAM_INVALID_HEADER ， 
} 
} 





当 mytest_upstream_process_header 返 回 NGX_OK 后 ，upstream 模 块 
开始 把 上 游 的 包 体 (如 果 有 的 话 ) 直接 转发 到 下 游客 户 端 。 


5.3.5 ”在 finalize_request 方 法 中 释放 资源 


当 请 求 结束 时 ， 将 会 回调 finalize_request 方 法 ， 如 果 我 们 希望 此 时 
释放 资源 ， 如 打开 的 句柄 等 ， 那 么 可 以 把 这 样 的 代码 添加 到 
finalize_request 方 法 中 。 本 例 中 定义 了 mytest_upstream_finalize_request 方 
法 ， 由 于 我 们 没有 任何 需要 释放 的 资源 ， 所 以 该 方法 没有 完成 任何 实际 
工作 ， 只 是 因为 upstream 模 块 要 求 必 须 实现 finalize_request 回 调 方 法 ， 如 
下 所 示 。 











static void 
mytest_upstream finalize request(ngx_http_request_t *r, ngx_int_t rc) 


ngx_l1og_error(NGX_LOG_DEBUG，r->connection->1og,0， 
"mytest_upstream finalize_request"); 





5.3.6 ”在 ngx_http_mytest_handler 方 法 中 启动 upstream 


在 开始 介入 处 理 客户 端 请 求 的 ngx_http_mytest_handler 方 法 中 启动 
upstream 机 制 ， 而 何 时 请 求 会 结束 ， 则 视 Nginx 与 上 游 的 google 服 务 器 间 
的 通信 而 定 。 通 常 ， 在 启动 upstream 时 ， 我 们 将 决定 以 何 种 方式 处 理 上 
游 啊 应 的 包 体 ， 前 文 说 过 ， 我 们 会 原封 不 动 地 转发 google 的 啊 应 包 体 到 
客户 端 ， 这 一 行为 是 由 ngx_http_request_t 结 构 体 中 的 
subrequest_in_memory 标 志 位 决定 的 ， 默 认 情况 下 ， 
subrequest_in_memory 为 0， 即 表示 将 转发 上 游 的 包 体 到 下 游 。 在 5.3.1 节 


中 介绍 过 ， 当 ngx_http_upstream_conf t 结 构 体 中 的 buffering 标 志 位 为 0 
时 ， 意 味 着 以 固定 大 小 的 缓冲 区 来 转发 包 体 。 








static ngx_int_t 
ngx_http_mytest_handler(ngx_http_request_t *r) 


// 首先 建立 


HTTP 上 下 文 结构 体 


ngx_http_mytest_ctx_t 





ngx_http_mytest_ctx_t* myctx = ngx_http_get module ctx(r,ngx_http_mytest_ module, 
if (myctx == NULL) 








myctx = ngx_palloc(r->pool, sizeof(ngx_http_mytest_ ctx_t)); 
if (myctx == NULL) 





return NGX_ERROR,; 


} 
// 将 新 建 的 上 下 文 与 请 求 关联 起 来 


ngx_http_set_ctx(r,myctx,ngx_http_mytest_module); 


} 
/* 对 每 


1 个 要 使 用 


upstream 的 请 求 ， 必 须 调用 且 只 能 调用 


工交 


ngx_http_upstream_create 方 法 ， 它 会 初始 化 


r->upstream 成 员 


i 


If (ngx_http_upstream create(r) != NGX_ OK) { 
ngx_log_error(NGX_LOG_ERR, r->connection->log, 0,"ngx_http_upstream create() 
return NGX_ERROR, 


} 
// 得 到 配置 结构 体 


ngx_http_mytest_conf_t 





ngx_http_mytest conf_t *mycf = (ngx_http mytest conf_ t *) ngx_http_get module_ 
ngx_http_upstream t *u = r->upstream; 








// 这 里 用 配置 文件 中 的 结构 体 来 典 给 


r->upstream->conf 成 员 


U->conf = &mycf->upstream; 
// 决定 转发 包 体 时 使 用 的 缓冲 区 


u->buffering = mycf->upstream.buffering; 
// 以 下 代码 开始 初始 化 


resolved 结 构 体 ， 用 来 保存 上 游 服务 器 的 地 址 


U->resolved = (ngx_http_upstream resolved t*) ngx_pcalloc(r->pool, sizeof(ngx_ht 
if (u->resolved == NULL) { 
ngx_log_error(NGX_LOG_ERR, r->connection->log, 0, 
"ngx_pcalloc resolved error. %s.", strerror(errno)); 
return NGX_ERROR, 


} 
// 这 里 的 上 游 服务 器 就 是 


www.google.com 

static struct sockaddr_in backendSockAddr; 

Struct hostent *pHost = gethostbyname((char*) "www.google.com"); 

if (pHost == NULL) 

{ 
ngx_log_error(NGX_LOG_ERR, r->connection->log, 0, 

"gethostbyname fail. %s", strerror(errno)); 

return NGX_ERROR, 


} 
// 访问 上 游 服务 器 的 


backendSockAddr .sin_ family = AF_INET; 

backendSockAddr .sin port = htons((in_ port_t) 80); 

char* pDmsIP = inet_ ntoa(*(struct in addr*) (pHost->h_addr_list[0])); 
backendSockAddr .sin addr.s addr = inet_addr(pDmsIP); 
myctx->backendServer ,data = (u_char*)pDmsIP; 

myctx->backendServer.len = strlen(pDmsIP); 

// 将 地 址 设置 到 


resolved 成 员 中 


Uu->resolved->sockaddr = (struct sockaddr *)&backendSockAddr ; 
Uu->resolved->socklen = sizeof(struct sockaddr_in); 
U->resolved->naddrs = 1; 


// 设置 


3 个 必须 实现 的 回调 方法 ， 也 就 是 


U->create_request = mytest_upstream_create_request 
U->process_header = mytest_process_status_ line,; 
U->finalize_request = mytest_upstream finalize_request; 
// 这 里 必须 将 


COUNt 成 员 加 
1， 参 见 


5.1.5 节 


r->main->count++; 
// 启动 


upstream 
ngx_http_upstream init(r); 
// 必须 返回 


NGX_DONE 
return NGX_DONE， 
} 





到 此 为 止 ， 高 性 能 地 访问 第 三 方 服 务 的 upstream 例 子 就 介绍 完了 。 
在 本 例 中 ， 可 以 完全 异步 地 访问 第 三 方 服务 ， 并 发 访问 数 也 只 会 受制 于 
物理 内 存 的 大 小 ， 完 全 可 以 轻松 达到 几 十 万 的 并 发 TCP 连 接 。 


5.4 ”subregquest 的 使 用 方式 


subrequest 是 由 HTTP 框 架 提 供 的 一 种 分 解 复杂 请 求 的 设计 模式 ， 它 
可 以 把 原始 请 求 分 解 为 许多 子 请 求 ， 使 得 诸多 请 求 协同 完成 一 个 用 户 请 
求 ， 并 且 每 个 请 求 只 关注 于 一 个 功能 。 它 与 访问 第 三 方 服务 及 upstream 
机 制 有 什么 关系 呢 ? 首先 ， 只 要 不 是 完全 将 上 游 服务 器 的 响应 包 体 转发 
到 下 游客 户 端 ， 基 本 上 都 会 使 用 subrequest 创 建 出 子 请 求 ， 并 由 子 请 求 
使 用 upstream 机 制 访 问 上 游 服 务 器 ， 然 后 由 父 请 求 根据 上 游 响应 重新 构 
造 返回 给 下 游客 户 端 的 啊 应 。 其 次 ， 在 HTTP 框 染 的 设计 上 ，subrequest 
与 upstream 也 是 密切 相关 的 。 例 如 ， 上 文 讲 过 ， 描 述 HTTP 请 求 的 
ngx_http_request_t 结 构 体 中 有 一 个 标志 位 subrequest_in_memory， 它 决定 
upstream 对 待 上 游 响应 包 体 的 行为 。 但 是 从 名 字 上 我 们 可 以 看 到 ， 它 是 
与 Subrequestf 有 关 的 ， 实 际 上 ， 在 创建 子 请 求 的 方法 中 就 可 以 设置 


subrequest_in memory。 








subrequest 设 计 的 基础 是 生成 一 个 〈 子 ) 请 求 的 代价 要 非常 小 ， 消 
耗 的 内 存 也 要 很 少 ， 并 且 不 会 一 直 占 用 进程 资源 。 因 此 ， 每 个 请 求 都 应 
该 做 简单 、 独 立 的 工作 ， 而 由 多 个 子 请 求 合 成 为 一 个 父 请 求 同 客 户 端 提 
供 完 整 的 服务 。 在 Nginx 中 ， 大 量 功能 复杂 的 模块 都 是 基于 subrequest 实 
现 的 。 


使 用 subrequest 的 方式 要 比 upstream 简 单 得 多 ， 只 需要 完成 以 下 4 步 
操作 即 可 。 


1) 在 nginx.conf 文 件 中 配置 好 子 请 求 的 处 理 方式 。 
2) 启动 subrequest 子 请 求 。 

3) 实现 子 请 求 执 行 结束 时 的 回调 方法 。 

4) 实现 父 请 求 被 激活 时 的 回调 方法 。 


下 面 依次 说 明 这 4 个 步骤。 


5.4.1 配置 子 请 求 的 处 理 方 式 


实际 上 ， 子 请 求 的 处 理 过 程 与 普通 请 求 完 全 相同 ， 也 需要 在 
nginx.conf 中 配置 相应 的 模块 来 处 理 。 子 请 求 与 普通 请 求 的 不 同 之 处 在 
于 ， 子 请 求 是 由 父 请 求生 成 的 ， 不 是 接收 客户 端 发 来 的 网 络 包 再 由 
HTTP 框架 解析 出 的 。 配 置 处 理子 请 求 的 模块 与 普通 请 求 完全 相同 ， 可 
以 任意 地 使 用 HTTP 官 方 模块 、 第 三 方 模块 来 处 理 。 本 章 中 将 以 访问 第 
三 方 服务 为 例 ， 因 此 会 使 用 ngx_http_proxy_module 反 向 代理 模块 来 处 理 
子 请 求 ( 注 意 ， 这 里 并 没有 使 用 反 向 代理 的 转发 响应 功能 ， 而 只 是 把 响 
应 接收 到 Nginx 的 内 存 中 ) ， 但 在 实际 应 用 中 不 限于 此 。 














假设 我 们 生成 的 子 请 求 是 以 URI 为 Mist 开 头 的 请 求 ， 使 用 
ngx_http_proxy_module 模 块 让 子 请 求 访问 新 浪 的 hq.sinajs.cn 股 票 服 务 
器 ， 那 么 可 以 在 nginx.conf 中 这 样 设 置 : 





location /list { 
proxy_pass http:// hq.sinajs.cn 


/* 不 希望 第 三 方 服务 发 来 的 


HTTP 包 体 做 过 


gzip 压 缩 ， 因 为 我 们 不 想 在 子 请 求 结束 时 要 对 响应 做 


gzip 解 压缩 操作 


*/ 
proxy_set_header Accept-Encoding "" 





这 样 ， 在 5.4.4 节 中 ， 如 果 生 成 的 子 请 求 是 以 Mist 开 头 的 ， 就 会 使 用 
反问 代理 模块 去 访问 新 浪 服 务 器 ， 并 在 接收 完 新 浪 服 务 器 的 响应 包 后 调 
用 5.4.2 节 中 介绍 的 回调 方法 。 


5.4.2 ”实现 子 请 求 处 理 完 毕 时 的 回调 方法 





Nginx 在 子 请 求 正 党 或 者 异常 结束 时 ， 都 会 调用 
ngx_http_post_subrequest_pt 回 调 方 法 ， 如 下 所 示 。 





typedef ngx_int_t (*ngx_http_post_ subrequest pt) (ngx_http_request t *r,void *data, 





如 何 把 这 个 回调 方法 传递 给 subrequest 子 请 求 呢 ?要 建立 
ngx_http_post_subrequest_t 结 构 体 : 





typedef struct { 
ngx_http_post_subrequest_pt handler; 
void *data; 

} ngx_http_post_subrequest_t; 





在 生成 ngx_http_post_subrequest_t 结 构 体 时 ， 可 以 把 任意 数据 赋 给 
这 里 的 data 指 针 ，ngx_http_post_subrequest_pt 回 调 方 法 执行 时 的 data 参 数 
就 是 ngx_http_post_subrequest_t 结 构 体 中 的 data 成 员 指 针 。 


ngx_http_post_subrequest_pt 回 调 方 法 中 的 rc 参数 是 子 请 求 在 结束 时 
的 状态 ， 它 的 取 值 则 是 执行 ngx_http_finalize_request 销 毁 请 求 时 传递 的 
rc 参数 〈 对 于 本 例 来 说 ， 由 于 子 请 求 使 用 反 向 代理 模块 访问 上 游 HTTP 
服务 器 ， 所 以 rc 此 时 是 HTTP 响 应 码 。 例 如 ， 在 正常 情况 下 ，rc 会 是 
200) 。 相 应 源 代码 如 下 : 





void 
ngx_http_finalize_request(ngx_http_request_t *r, ngx_int_t rc) 


// 如 果 当 前 请 求 属于 某 个 原始 请 求 的 子 请 求 


if (r != r->main && r->post_subrequest) { 
rc = r->post_subrequest->handler(r, r->post_subrequest->data, rc); 


} 





上 面 代码 中 的 r 变 量 是 子 请 求 〈 不 是 父 请 求 ) 。 


在 ngx_http_post_subrequest_pt 回 调 方法 内 必须 设置 父 请 求 激活 后 的 
处 理 方法 ， 设 置 的 方法 很 简单 ， 首 先 要 找 出 父 请 求 ， 例 如 : 





ngx_http_request_t *pr = r->parent; 





然后 将 实现 好 的 ngx_http_event_handler_pt 回 调 方 法 赋 给 父 请 求 的 
write_event_handler 指 针 (为 什么 设置 write_event_handler? 因为 父 请 求 
正 处 于 等 竺 发 送 啊 应 的 阶段 ， 详 见 11.7 节 ) ， 例 如 : 





pr->write_event_handler = mytest_post_handler ; 








mytest_post_handler 就 是 5.6.4 节 中 实现 的 父 请 求 重 新 激活 后 的 回调 
方法 O 


在 5.6.3 市 中 可 以 看 到 相关 的 具体 例子 。 


5.4.3 ”处 理 父 请 求 被 重新 激活 后 的 回调 方法 





mytest_post_handler 是 父 请 求 重新 激活 后 的 回调 方法 ， 它 对 应 于 
ngx_http_event_handler_pt 指 针 ， 如 下 所 示 : 





typedef void (*ngx_http_event_handler_pt)(ngx_http_request t *r); 


struct ngx_http_redquest_s { 


ngx_http_event_handler_pt write_ event_handler; 





这 个 方法 负责 发 送 啊 应 包 给 用 户 ， 其 流程 与 3.7 节 中 介绍 的 发 送 方 
式 是 一 致 的 ， 也 可 以 参考 5.6.4 节 中 的 例子 。 


5.4.4 ”启动 subrequest 子 请 求 


在 ngx_http_mytest_handler 处 理 方法 中 ， 可 以 启动 subrequest 子 请 
求 。 首 先 调 用 ngx_http_subrequest 方 法 建立 subrequest 子 请 求 ， 在 
ngx_http_mytest_handler 返 回 后 ，HTTP 框 架 会 自动 执行 子 请 求 。 先 看 一 


下 ngx_http_subrequest 的 定义 : 





ngx_int_t 

ngx_http_subrequest(ngx_http_request_t *r, 
ngx_str_t *uri, ngx_str_t *args, ngx_http_request _t **psr, 
ngx_http_post_subrequest_t *ps, ngx_uint_t flags); 





下 面 依次 介绍 ngx_http_subrequest 中 的 参数 和 返回 值 。 
(1) ngx_http_request_t*r 


ngx_http_request_t*r 是 当前 的 请 求 ， 也 就 是 父 请 求 。 


(2) ngx_str_t*uri 


ngXx_str_txuri 是 子 请 求 的 URI， 它 对 究竟 选用 nginx.conf 配 置 文件 中 
的 哪个 模块 来 处 理子 请 求 起 决定 性 作用 。 








(3) ngx_str_t*args 


ngx_str_t*args 是 子 请 求 的 URI 参 数 ， 如 果 没 有 参数 ， 可 以 传送 


NULL 空 指针 。 
(4) ngx_http_request_ t**psr 


psr 是 输出 参数 而 不 是 输入 参数 ， 它 将 把 ngx_http_subrequest 生 成 的 
子 请 求 传 出 来 。 一 般 ， 我 们 先 建立 一 个 子 请 求 的 空 指 针 
ngx_http_request_tspsr， 再 把 它 的 地 址 &psr 传 入 到 ngx_http_subrequest 方 
法 中 ， 如 果 ngx_http_subrequest 返 回 成 功 ，psr 就 指 同 建立 好 的 子 请 求 。 


(5) ngx_http_post_subrequest_t*ps 


这 里 传 入 5.4.2 节 中 创建 的 ngx_http_post_subrequest_t 结 构 体 地 址 ， 
它 指 出 子 请 求 结束 时 必须 回调 的 处 理 方法 。 


(6) ngx_uint t flags 





flag 的 取 值 范 围 包括 : (D0。 在 没有 特殊 需求 的 情况 下 都 应 该 填写 
它 ，@NGX_HTTP_SUBREQUEST_IN_MEMORY。 这 个 宏 会 将 子 请 求 


的 subrequest_in_memory 标 志 位 置 为 1， 这 意味 着 如 果子 请 求 使 用 
upstream 访 问 上 游 服 务 器 ， 那 么 上 游 服务 器 的 响应 都 将 会 在 内 存 中 处 
理 ， NGX_HTTP_ SUBREQUEST_ WAITED。 这 个 宏 会 将 子 请 求 的 
waited 标 志 位 置 为 1， 当 子 请 求 提 前 结束 时 ， 有 个 done 标 志 位 会 置 为 1， 
但 目前 HTTP 框 架 并 没有 针对 这 两 个 标志 位 做 任何 实质 性 处 理 。 注 意 ， 
flag 是 按 比 特 位 操作 的 ， 这 样 可 以 同时 含有 上 述 3 个 值 。 








(7) 返回 值 


返回 NGX_OK 表 示 成 功 建立 子 请 求 ， 返 回 NGX_ERROR 表 示 建 立 子 
请 求 失 败 。 


ngx_http_mytest_handler 处 理 方法 的 返回 值 依 然 与 upstream 机 制 相 
同 ， 它 也 必须 返回 NGX_DONE， 原 因 也 是 相同 的 。 





5.5 ”subrequest 执 行 过 程 中 的 主要 场景 





在 使 用 subrequest 时 ， 需 要 了 解 下 面 3 个 场景 : 
. 启动 subrequest 后 子 请 求 是 如 何 运行 的 。 
` 子 请 求 如 何 存放 接收 到 的 响应 。 
` 子 请 求 结 束 时 如 何 回调 处 理 方法 ， 以 及 激活 父 请 求 的 处 理 方法 。 


下 面 根据 序列 图 来 说 明 这 3 个 场景 。 


5.5.1 ”如 何 启 动 subrequest 


处 理 父 请 求 的 过 程 中 会 创建 子 请 求 ， 在 父 请 求 的 处 理 方法 返回 
NGX_DONE 后 ，HTTP 框 架 会 开始 执行 子 请 求 ， 如 图 5-6 所 示 。 


下 面 简单 介绍 一 下 图 5-6 中 的 每 一 个 步骤 : 





1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事件 发 
3 


2) 事件 模块 发 现 这 个 请 求 的 回调 方法 属于 HTTP 框 架 ， 交 由 HTTP 
框架 来 处 理 请 求 。 


3) 根据 解析 完 的 URI 来 决定 使 用 哪个 location 下 的 模块 来 处 理 这 个 
请 求 。 


1 


1 检查 是 奋 有 网 络 事件 | 





4. 油 用 mytest 模块 的 处 理 方 法 


| 
RE 3. 检查 location 时 发 现 应 由 mytest 模 块 处 理 








| 
1 
1 
| 
1 
5. 设置 subrequest 的 URI 和 回调 方 法 | 


有 


6 .调用 ngx_http _sub_request 方法 创建 子 请 求 


,> 7. 将 子 请 求 


8 .设置 好 subrequest 参数 即 返回 


[到 原始 请 求 的 posted _requests 链表 


“10. 由 于 具有 


a 


| 
| 
| 
| 
| 
1 

3 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
子 请 求 , 所 以 继续 处 理子 请 求 
I 
I 


一 根据 URI 和 配 轩 文件 决定 由 反 咎 代理 模块 处理 
| 
| 
12 .调用 反 向 代理 模块 的 人 口 方法 来 处 理子 请 求 
一 > 


13 .返回 NGX_DONE 


Ne 14. rhkit, 发 现 当前 请 求 没有 其 他 子 请 求 
15. 交 制约 伯 


图 5-6 ”subrequest 的 启动 过 程序 列 图 


4) 调用 mytest 模 块 的 ngx_http_mytest_handler 方 法 处 理 这 个 请 求 。 


5) 设置 subrequest 子 请 求 的 URI 及 回调 方法 ， 这 一 步 以 及 下 面 的 第 
6~9 步 所 做 的 工作 参见 5.4.4 节 。 


6) 调用 ngx_http_subrequest 方 法 创建 子 请 求 。 


7) 创建 的 子 请求 会 添加 到 原始 请 求 的 posted_requests 链 表 中 ， 这 样 
保证 第 10 步 时 会 在 父 请 求 返回 NGX_DONE 的 情况 下 开始 执行 子 请 求 。 

8) ngx_http_subrequest 方 法 执行 完毕 ， 子 请 求 创 建成 功 。 

9) ngx_http_mytest_handler 方 法 执行 完毕 ， 返 回 NGX_DONE， 这 样 
父 请 求 不 会 被 销毁 ， 将 等 待 以 后 的 再 次 激活 。 


10) HTTP 框 架 执行 完 当 前 请 求 〈 父 请 求 ) 后 ， 检 查 posted_requests 
链表 中 是 否 还 有 子 请 求 ， 如 果 存 在 子 请 求 ， 则 调用 子 请 求 的 
write_event_handler 方 法 《〈 详 见 11.7 节 ) 。 





11) 根据 子 请 求 的 URI《〈 第 5 步 中 建立 ) ， 检 查 nginx.conf 文 件 中 所 
有 的 location 配 置 ， 确 定 应 由 哪个 模块 来 执行 子 请 求 。 在 本 章 的 例子 
中 ， 子 请 求 是 交 由 反 同 代理 模块 执行 的 。 








12) 调用 反 回 代理 模块 的 入 口 方法 ngx_http_proxy_handler 来 处 理子 
请 求 。 


13) 由 于 反 回 代理 模块 使 用 了 upstream 机 制 ， 所 以 它 也 要 通过 许多 


次 的 异步 调用 才能 完整 地 处 理 完 子 请 求 ， 这 时 它 的 入 口 方 法 会 返回 
NGX_DONE (非常 类 似 5.1.5 节 中 的 内 容 〉。 








14) 再 次 检查 是 合 还 有 子 请 求 ， 这 时 会 及 现 已 经 没有 子 请 求 需要 执 
行 了 。 当 然 ， 子 请 求 可 以 继续 建立 新 的 子 请 求 ， 只 是 这 里 的 反问 代理 模 
块 不 会 这 样 做 。 





15〉 当 第 2 步 中 的 网 络 读 取 事件 处 理 完毕 后 ， 交 还 控制 权 给 事件 模 
块 。 


16) 当 本 轮 网 络 事件 处 理 完毕 后 ， 交 还 控制 权 给 Nginx 主 循环 。 





5.5.2 ”如 何 转 有 多 个 子 请 求 的 啊 应 包 体 


ngx_http_postpone_filter_module 过 滤 模 块 实际 上 是 为 了 subrequest 功 
能 而 建 并 的 ， 本 章 的 例子 虽然 没有 用 到 postpone (能够 应 用 到 的 场合 其 
实 非常 少 ，， 这 里 还 是 要 介绍 一 下 这 个 过 小 模 块 希望 解决 什么 样 的 问 
题 ， 这 样 读 者 会 对 postpone 模 块 和 subrequest 间 的 关系 有 更 深刻 的 了 解 。 


当 派 生 一 个 子 请 求 访问 第 三 方 服务 时 ， 如 果 只 是 希望 接收 到 完整 的 
啊 应 后 在 Nginx 中 解析 、 处 理 ， 那 么 这 里 束 不 需要 postpone 模 块 ， 就 像 
5.6 节 中 的 例子 那样 处 理 即 可 :如果 原始 请 求 派生 出 许多 子 请 求 ， 并 且 
硕 望 将 所 有 子 请 求 的 啊 应 依次 转发 给 客户 器， 当然 ， 这 里 的 “依次 ? 束 是 





按照 创建 子 请 求 的 顺序 来 发 送 啊 应 ， 这 时 ，postpone 模 块 就 有 了 “用 武之 
地 。Nginx 中 的 所 有 请 求 都 是 异步 执行 的 ， 后 创建 的 子 请 求 可 能 优先 执 
行 ， 这 样 转 发 到 客户 端的 啊 应 就 会 产生 混乱 。 而 postpone 模 块 会 强制 地 
把 竺 转发 的 啊 应 包 体 放 在 一 个 链表 中 发 送 ， 只 有 优先 转发 的 子 请 求 结 束 
后 才 会 开始 转发 下 一 个 子 请 求 中 的 啊 应 。 下 面 介绍 一 下 它 是 如 何 实现 
的 。 




















每 个 请 求 的 ngx_http_request t 结 构 体 中 都 有 一 个 postponed 成 员 : 





Struct ngx_http_redquest_s { 


ngx_http_postponed_request_t *postponed; 





它 实 际 上 是 一 个 链表 : 





typedef struct ngx_http_postponed_ request_ s ngx_http_postponed request tt; 
struct ngx_http_postponed request s { 


ngx_http_request_t *request; 
ngx_chain_t *out,; 
ngx_http_postponed_request_t *next; 


}; 





从 上 述 代码 可 以 看 出 ， 多 个 ngx_http_postponed_request_t 之 间 使 用 
next 指 针 连 接 成 一 个 单 向 链表 。ngx_http_postponed_request_t 中 的 out 成 
员 是 ngx_chain t 结 构 ， 它 指 问 的 是 来 自 上 游 的 、 将 要 转发 给 下 游 的 啊 应 





包 体 。 


每 当 使 用 ngx_http_output_filter 方 法 〈 反 向 代理 模块 也 使 用 该 方法 转 
发 响应 ) 向 下 游 的 客户 端 发 送 响应 包 体 时 ， 都 会 调用 到 
ngx_http_postpone_filter_ module 过 滤 模 块 处 理 这 段 要 发 送 的 包 体 。 下 面 
看 一 下 过 滤 包 体 的 ngx_http_postpone_filter 方 法 (在 阅读 完 第 11 章 后 再 回 
头 看 这 段 代 码 ， 概 念 可 能 会 更 加 清晰 ) : 





// 这 里 的 参数 


in 就 是 将 要 发 送 给 客户 端的 一 段 包 体 ， 第 


6 章 会 详 述 


HTTP 过 滤 模 块 


static ngx_int_ 
ngx_http_postpone_filter(ngx_http_request_t *r, ngx_chain_t *in) 


ngx_connection_t SG 
ngx_http_postponed_redquest t *pr; 
// C 是 


Nginx 与 下 游客 户 端 间 的 连接 ， 


C->data 保 存 的 是 原始 请 求 


Cc = r->connection,; 
// 如 果 当 前 请 求 


"是 一 个 子 请 求 (因为 


C->data 指 向 原始 请 求 ) 


if (r != c->data) { 


/* 如 果 待 发 送 的 
in 包 体 不 为 空 ， 则 把 
in 加 到 
postponed 链 表 中 属于 当前 请 求 的 
ngx_http_postponed_request_t 结 构 体 的 
OUt 链 表 中 ， 同 时 返回 
NGX_OK， 这 意味 着 本 次 不 会 把 
in 包 体 发 给 客户 端 


*/ 
if (in) { 
ngx_http_postpone_filter_ add(r, in); 
return NGX_OK; 
// 如 果 当 前 请 求 是 子 请 求 ， 而 
in 包 体 又 为 空 ， 那么 直接 返回 即 可 
return NGX_OK; 
} 
// 如 果 


postponed 为 空 ， 表示 请 求 


『 没 有 子 请 求 产生 的 响应 需要 转发 


If (r->postponed == NULL) { 
/* 直 接 调 用 下 一 个 


HTTP 过 滤 模 块 继续 处 理 
in 包 体 即 可 。 如 果 没 有 错误 的 话 ， 就 会 开始 向 下 游客 户 端 发 送 响 应 


*/ 
if (in || c->buffered) { 
return ngx_http_next_filter(r->main, in); 


} 
return NGX_OK; 


/* 至 此 ， 说 明 
postponed 链 表 中 是 有 子 请 求 产 生 的 响应 需要 转发 的 ， 可 以 先 把 
in 包 体 加 到 待 转发 响应 的 末尾 


*/ 
if (in) { 
ngx_http_postpone_filter add(r, in); 
} 
// 循环 处 理 


postponed 链 表 中 所 有 子 请 求 待 转发 的 包 体 


do { 
pr = r->postponed; 
/* 如 果 


pr->request 是 子 请 求 ， 则 加 入 到 原始 请 求 的 
posted_requests 队 列 中 ， 等 待 


HTTP 框 架 下 次 调用 这 个 请 求 时 再 来 处 理 ( 参 见 


和 了 区 
*/ 
if (pr->request) { 
r->postponed = pr->next; 
c->data = pr->request,; 
return ngx_http_post_request(pr->request, NULL); 
} 
// 调用 下 一 个 
HTTP 过 小 模块 转发 


Out 链表 中 保存 的 待 转发 的 包 体 


if (pr->out == NULL) { 
} else { 
If (ngx_http_next_filter(r->main, pr->out) == NGX_ERROR) { 
return NGX_ERROR,; 
} 


// 遍历 完 


postponed 链 表 


r->postponed = pr->next; 
} while (r->postponed); 
return NGX_OK， 
} 





图 5-7 展 示 了 使 用 反问 代理 模块 转发 子 请 求 的 包 体 的 一 般 流 程 ， 其 
中 的 第 5 步 正 是 上 面 介绍 的 ngx_http_postpone_filter 方 法 。 


下 面 简单 地 介绍 一 下 图 5-7 中 的 每 一 个 步 又 : 





1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事件 发 
2 


2) 事件 模块 发 现 这 个 请 求 的 回调 方法 属于 反问 代理 模块 的 接收 
HTTP 包 体 阶段 ， 于 是 交 由 反问 代理 模块 来 处 理 。 
3) 读 取 上 游 服 务 器 友 来 的 包 体 。 


4) 对 于 接收 到 的 字符 流 ， 会 依次 调用 所 有 的 HTTP 过 滤器 模块 来 转 
发 包 体 。 其 中 ， 还 会 调用 到 postpone 过 滤 模 块 ， 这 个 模块 将 会 处 理 设置 
在 子 请 求 中 的 ngx_http_postponed_request_t 链 表 。 


5) postpone 模 块 使 用 ngx_http_postpone_filter 方 法 将 待 转发 的 包 体 
以 合适 的 顺序 再 进行 整理 发 送 到 下 游客 户 端 。 如 果 


ngx_http_postpone_filter 方 法 没有 通过 ngx_http_next_filter 方 法 继续 调用 

其 他 HTTP 过 小 模块 (如 由 于 顺序 的 原因 而 暂停 转发 茶 个 子 请 求 的 啊 应 
包 体 ) ， 将 会 直接 跳 到 第 7 步 ， 否 则 继续 处 理 这 段 接 收 到 的 包 体 (第 6 
2 











1. 检 查 是 否 有 网 络 事 件 


| i a Re 
2. 回调 当前 读 事件 的 处 理 方法 





> 3. 读 取 上 游 发 来 的 响应 


4. 洞 用 postpone 过 滤 模 块 处 理 接收 到 | 的 : 玉 符 流 


ee 





6. 继续 调用 其 他 过 滤器 ， 全 部 执行 完 后 返回 
[一 = 
| 
| 
| 交还 控制 权 给 事件 模块 
| | 
8. 本 次 网 络 事件 处 理 完毕 | 
a ptt bet ine nt cine sep ood Sein ed 
| | 


图 5-7 子 请 求 转发 HTTP 包 体 过 程 的 序列 图 


6) 继续 调用 其 他 HTTP 过 滤 横 块 ， 待 所 有 的 过 滤 模 块 执行 完毕 后 将 
控制 权 交还 给 反 向 代理 模块 。 


7) 当 第 2 步 中 的 网 络 读 取 事 件 处 理 完毕 后 ， 交 还 控制 权 给 事件 模 
块 。 


8) 当 本 轮 网 络 事件 处 理 完毕 后 ， 交 还 控制 权 给 Nginx 主 循环 。 


5.5.3” 子 请 求 如 何 激活 父 请 求 


子 请 求 在 结束 前 会 回调 在 ngx_http_post_subrequest_t 中 实现 的 
handler 方 法 〈 见 5.4.2 节 ) ， 在 这 个 handler 方 法 中 ， 又 设置 了 父 请 求 被 激 
活 后 的 执行 方法 mytest_post_handler， 流 程 如 图 5-8 所 示 。 


下 面 简单 地 介绍 一 下 图 5-8 中 的 每 一 个 步骤 : 





1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事件 发 
生 。 


2) 如 果 事 件 模块 检测 到 连接 关闭 事件 ， 而 这 个 请 求 的 处 理 方法 属 
于 upstream 模 块 ， 则 交 由 upstream 模 块 来 处 理 请 求 。 


3) upstream 模 块 开 始 调用 ngx_http_upstream_finalize_request 方 法 来 
结束 upstream 机 制 下 的 请 求 〈 详 见 12.9 节 ) 。 


HTTP 框 架 | | 反 向 代理 &upstream 模块 事件 模块 





| 
1. 检 查 是 否 有 网 络 事件 





| 
| 
IE | 
pe 3. upstream 销 女子 请 求 


4.finalize 销毁 子 请 求 
5. 回调 子 请 求 的 处 理 方法 


i 





6. 解 析 子 请 求 的 响应 , 并 设置 父 请 求 的 回调 方法 


| 


| 8. finalize 执行 完毕 
一 





| 
| 
10. 构造 向 用 户 发 送 的 响应 包 
| 
11. 调 用 发 送 方法 将 响应 发 给 客户 端 





; 14. 事件 处 理 完毕 
15. 本 次 网 络 事件 处 理 完毕 


| 
| 
图 5-8” 子 请 求 激活 父 请 求 过 程 的 序列 图 


4) 调用 HTTP 框 架 提 供 的 ngx_http_finalize_request 方 法 来 结束 子 请 
求 o 











5) ngx_http_finalize_request 方 法 会 检查 当前 的 请 求 是 否 是 子 请 求 ， 
如 果 是 子 请 求 ， 则 会 回调 post_subrequest 成 员 中 的 handler 方 法 (参见 图 
11-26 中 的 第 5 步 ) ， 也 就 是 会 调用 mytest_subrequest_post_handler 方 法 


( 见 5.6.3 节 ) 。 





6) 在 实现 的 子 请 求 回调 方法 中 ， 解 析 子 请 求 返 回 的 啊 应 包 。 注 
意 ， 这 时 需要 通过 write _event_handler 设 置 父 请 求 被 激活 后 的 回调 方法 
《因为 此 时 父 请 求 的 回调 方法 已 经 被 HTTP 框架 设置 为 什么 事 都 不 做 的 


ngx_http_request_empty_handler 方 法 ， 详 见 第 11 章 ) 。 
7) 子 请 求 的 回调 方法 执行 完毕 后 ， 交 由 HTTP 框架 的 
ngXx_http_finalize request 方法 继续 癌 下 执行 。 


和 


8) ngx_http_finalize_request 方 法 执行 完毕 。 








9) HTTP 框 架 如 果 发 现 当前 请 求 后 还 有 父 请 求 需要 执行 ， 则 调用 父 


请 求 的 write_event_handler 回 调 方 法 。 


10) 这 里 可 以 根据 第 6 步 中 解析 子 请 求 啊 应 后 的 结果 来 构造 啊 应 
包 。 


11) 调用 无 阻塞 的 ngx_http_send_header、ngx_http_output_filter 发 送 
方法 ， 同 客户 站 发 送 啊 应 包 。 


12) 无 阻塞 发 送 方法 会 立刻 返回 。 即 使 目前 未 发 送 完 ，Nginx 之 后 





也 会 异步 地 发 送 完 所 有 的 啊 应 包 ， 然 后 再 结束 请 求 。 
13) 父 请 求 的 回调 方法 执行 完毕 


14) 当 第 2 步 中 的 上 游 服 务 咒 连接 关闭 事件 处 理 完 毕 后 ， 交 还 控制 
权 给 事件 模块 。 


15) 当 本 轮 网 络 事件 处 理 完毕 后 ， 交 还 控制 权 给 Nginx 主 循环 。 


5.6 ”subrequest 使 用 的 例子 


下 面 以 一 个 简单 的 例子 说 明 subrequest 的 用 法 。 场 景 很 简单 ， 当 使 
用 浏览 器 访问 /query?s_sh000001 时 (s_sh000001 是 新 浪 服 务 器 上 的 A 上 股 
上 证 指数 ) ，Nginx 由 mytest 模 块 处 理 ， 它 会 生成 一 个 子 请 求 ， 由 反 向 代 
理 模块 处 理 这 个 子 请 求 ， 访 问 新 浪 的 http://hg.sinajs.cn 服务 器 ， 这 时 子 
请 求 得 到 的 啊 应 包 是 上 证 指数 的 当天 价格 交易 量 等 信息 ， 而 mytest 模 块 
会 解析 这 个 响应 ， 重 新 构造 发 往 客 户 端 浏览 器 的 HTTP 啊 应 。 浏 览 器 得 
到 的 返回 值 格式 为 : stock[ 上 证 指数 ]，Today current 
price:2373.436,volumn:770。 当 然 ， 如 果 传 入 的 参数 不 仅 是 s_sh000001， 
也 可 以 是 任意 新 浪 服 务 器 识别 的 股票 代码 ， 如 s_sh000009 代 表 上 证 
380。 








这 个 例子 说 明 如 何 生 成 子 请 求 ， 以 及 子 请 求 如 何 通 过 配置 文件 配置 
为 反问 代理 服务 器 以 访问 新 滔 ， 并 试图 将 新 溪 的 返回 内 容 全 部 保存 在 一 
块 内 存 缓冲 区 中 ， 最 后 解析 缓冲 区 中 的 内 容 生 成 HTTP 啊 应 返回 给 浏览 
虱 等 过 程 。 这 里 的 限制 条 件 是 内 存 缓冲 区 的 大 小 要 可 以 容纳 完整 的 新 浪 
服务 器 的 响应 ， 它 实际 上 是 由 ngx_http_upstream_conf t 结 构 体 内 的 
buffer_size 参 数 决定 的 〈 见 5.3.1 节 ) ， 而 对 于 反 向 代理 模块 来 说 ， 就 是 
由 nginx.conf 文 件 中 的 proxy_buffer_size 配 置 项 决定 的 。 如 果 新 浪 这 样 的 
上 游 服务 需 返 回 的 HITP 啊 应 大 于 缓冲 区 大 小 ， 请 求 将 会 出 错 ， 这 时 要 








么 增 大 proxy_buffer_size 配 置 的 值 ， 要 么 不 能 再 选择 反 辐 代理 模块 访问 
上 游 服 务 器 ， 而 要 自己 使 用 upstream 机 制 编写 相应 的 HITP 模 块 解 析 上 游 
服务 器 的 啊 应 包 体 。 


5.6.1 配置 文件 中 子 请 求 的 设置 





若 访问 新 浪 服务 器 的 URL 为 /list=s_sh000001， 则 可 以 这 样 配 置 : 





location /list { 
// 决定 访问 的 上 游 服 务 器 地 址 是 


hq.sinajs.cn 
proxy_pass http://hq.sinajs.cn 


// 不 希望 第 三 方 服务 发 来 的 


HTTP 包 体 进 行 过 


gzip 压 缩 


proxy_set_header Accept-Encoding "" 





当然 ， 处 理 以 /query 开 头 的 URI 用 户 请 求 还 需 选 用 mytest 模 块 ， 例 
如 : 





location /query { 
mytest; 





56.2 请 求 上 下 文 








这 里 的 上 下 文 仅 用 于 保存 子 请 求 回 调 方 法 中 解析 出 来 的 股票 数据 ， 
如 下 所 示 : 





typedef struct { 
ngx_str_t stock[6]; 
} ngx_http_mytest_ ctx_t; 








新 浪 服 务 器 的 返回 大 致 如 下 : 





Var hq_str_s_sh000009=" 上 证 


380, 3356.355, -5.725, -0.17,266505, 2519967"; 





上 段 代 码 中 引号 内 的 6 项 值 《 以 乏 号 分 隔 ) 就 是 解析 出 的 值 。 在 父 
请 求 的 回调 方法 中 ， 将 会 用 到 这 6 个 值 。 


5.6.3 ” 子 请 求 结束 时 的 处 理 方法 


定义 mytest_subrequest_post_handler 作 为 子 请 求 结束 时 的 回调 方法 ， 
如 下 所 示 : 





static ngx_int_t mytest_ subrequest post_ handler(ngx_http_request _t *r, 
void *data, ngx_int_t rc){ 
// 当前 请 求 


parent 成 员 指向 父 请 求 


ngx_http_request_t *pr = r->parent; 
/* 注 意 ， 由 于 上 下 文 是 保存 在 父 请 求 中 的 (参见 


5.6.5 节 ) ， 所 以 要 由 


pr 取 上 下 文 。 其 实 有 更 简单 的 方法 ， 即 参数 


data 就 是 上 下 文 ， 初 始 化 


subrequest 时 就 对 其 进行 设置 。 这 里 仅 为 了 说 明 如 何 获取 到 父 请 求 的 上 下 文 


*/ 
ngx_http_mytest_ctx_t* myctx = ngx_http_get module ctx(pr,ngx_http_ mytest module 
pr->headers_out,status = r->headers_ out,.status,; 
/* 如 果 返 回 








NGX_HTTP_OK (也 就 是 


200) ， 则 意味 着 访问 新 浪 服务 器 成 功 ， 接 着 将 开始 解析 


HTTP 包 体 


*/ 


If (r->headers_ out.status == NGX_HTTP_OK) 


int flag = 09; 


/* 在 不 转发 响应 时 ， 


buffer 中 会 保存 上 游 服务 器 的 响应 。 特 别 是 在 使 用 反 向 代理 模块 访问 上 游 服 务 器 时 ， 如 果 它 使 用 


Upstream 机 制 时 没有 重 定义 


input_filter 方 法 ， 


Upstream 机 制 默 认 的 


input_filter 方 法 会 试图 把 所 有 的 上 游 响 应 全 部 保存 到 


buffer 缓 冲 区 中 


*/ 


ngx_buf_t* pRecvBuf = &r->upstream->buffer; 
/* 以 下 开始 解析 上 游 服 务 器 的 响应 ， 并 将 解析 出 的 值 赋 到 上 下 文 结构 体 


myctx->stock 数 组 中 


*/ 
for (;pRecvBuf->pos != pRecvBuf->last; pRecvBuf->pos++) 
if (*pRecvBuf->pos == ',' || *pRecvBuf->pos == '\"') 
if (flag > 0) 
{ 
myctx->stock[flag-1].len = pRecvBuf->pos-myctx->stock[flag-1].date 
} 
flag++; 
myctx->stock[flag-1].data = pRecvBuf->pos+1; 
} 
if (flag > 6) 
break; 
} 
// 设置 接 下 来 父 请 求 的 回调 方法 ， 这 一 步 很 重要 
pr->write event_handler = mytest_post_handler ; 
return NGX_OK， 
} 





5.6.4” 父 请 求 的 回调 方法 


将 父 请 求 的 回调 方法 定义 为 mytest_post_handler， 如 下 所 示 : 





static void 
mytest_post_handler(ngx_http_request _t *r) 


// 如 果 没 有 返回 


200， 则 直接 把 错误 码 发 回 用 户 


If (r->headers out.status != NGX_HTTP_OK) 


ngx_http_finalize request(r, r->headers_ out.status); 
return; 


} 
// 当前 请 求 是 父 请 求 ， 直 接 取 其 上 下 文 


ngx_http_mytest_ctx_t* myctx = ngx_http_get module ctx(r,ngx_http_ mytest module, 
/* 定 义 发 给 用 户 的 








HTTP 包 体内 容 ， 格 式 为 : 


stock[:… 


],Today current price: 


;， VOolumn: 


*/ 
ngx_str_t output_format = ngx_string("stock[%V],Today current price: %V, volumn.: 
// 计算 待 发 送 包 体 的 长 度 


int bodylen = output_format.len + myctx->stock[0].1len 
+myctx->stock[1].len+myctx->stock[4].len-6; 

r->headers_ out.content_length_n = bodylen; 

// 在 内 存 池上 分 配 内 存 以 保存 将 要 发 送 的 包 体 


ngx_buf_t* b = ngx_create temp_buf(r->pool, bodylen); 

ngx_snprintf(b->pos, bodylen, (char*)output_ format.data, 
&myctx->stock[0],&myctx->stock[1],é&myctx->stock[4]); 

b->last = b->pos + bodylen,; 

b->last_buf = 1; 

ngx_chain_t out; 


out.buf = b; 
out.next = NULL; 
// 设置 


Content-Type， 注 意 ， 在 汉字 编码 方面 ， 新 浪 服务 器 使 用 了 


GBK 
static ngx_str_t type = ngx_string("text/plain; charset=GBK"); 
r->headers_out.content_type = type; 
r->headers_out.status = NGX_HTTP_OK; 
r->connection->buffered |= NGX_HTTP_WRITE_BUFFERED; 
ngx_int_t ret = ngx_http_send_header(r); 
ret = ngx_http_output_filter(r, &out); 
/* 注 意 ， 这 里 发 送 完 响应 后 必须 手动 调用 


ngx_http_finalize_request 结 束 请 求 ， 因 为 这 时 





HTTP 框 架 不 会 再 帮忙 调用 它 
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ngx_http_finalize_request(r, ret); 





5.0.5 


启动 subrequest 


在 处 理 用 户 请 求 的 ngx_http_mytest_handler 方 法 中 ， 开 始 创 建 
subrequest 子 请 求 。ngx_http_mytest_handler 方 法 的 完整 实现 如 下 所 示 : 





static ngx_int_t 











ngx_http_mytest_handler(ngx_http_request_t *r) 
// 创建 
HTTP 坟 下 交 
ngx_http_mytest_ctx_t* myctx = ngx_http_get module ctx(r,ngx_http_mytest module, 
if (myctx == NULL) 
{ 
myctx = ngx_palloc(r->pool, sizeof(ngx_http_mytest_ctx_t)); 
if (myctx == NULL) 
return NGX_ERROR ， 
} 
// 将 上 下 文 设置 到 原始 请 求 
r 中 
ngx_http_set_ctx(r,myctx,ngx_http_mytest_module); 
} 
// ngx_http_post_subrequest_t 结 构 体 会 决定 子 请 求 的 回调 方法 ， 参 见 
5.4.1 节 


ngx_http_post_subrequest_t *psr = ngx_palloc(r->pool, sizeof(ngx_http_post_subre 
If (psr == NULL) { 
return NGX_HTTP_INTERNAL_SERVER_ERROR; 


} 
// 设置 子 请 求 回调 方法 为 


mytest_subrequest_post_handler 


psr->handler = mytest_subrequest_post_handler; 


/将 


data 设 为 


myctx 上 下 文 ， 这 样 回调 


mytest_subrequest_post_handler 时 传 入 的 


data 参 数 就 是 


myctx*/ 
psr->data = myctx; 
/* 子 请 求 的 


URI 前 级 是 


/list， 这 是 因为 访问 新 浪 服 务 器 的 请 求 必须 是 类 似 





/list=s_sh000001 的 


URI， 这 与 在 


nginx.conf 中 配置 的 子 请 求 


]ocation 的 


URI 是 一 致 的 ( 见 


ngx_str_t sub_prefix = ngx_string("/list="); 


ngx_str_t sub_location; 


sub_location.len = sub_prefix.len + r->args.1en; 


sub_location.data = ngx_palloc(r->pool, 


sub_location.1en); 


ngx_snprintf(sub_location.data, sub_location.1len, 


"%V%V", &sub_prefix,&r->args); 


// Sr 就 是 子 请 求 


ngx_http_request_t *sr; 


/A* 调 用 


ngx_http_subrequest 创 建 子 请 求 ， 它 只 会 返回 


NGX_OK 或 者 

NGX_ERROR。 返 回 

NGX_OK 时 ， 

Sr 已 经 是 合法 的 子 请 求 。 注 意 ， 这 里 的 
NGX_HTTP_SUBREQUEST_IN_MEMORY 参 数 将 告诉 
UpSstream 模 块 把 上 游 服务 器 的 响应 全 部 保存 在 子 请 求 的 
Sr->upstream->buffer 内 存 缓冲 区 中 


*/ 
ngx_int_t rc = ngx_http_subrequest(r, &sub_ location, NULL, &sr, psr, NGX_HTTP_S\ 
if (rc != NGX_OK) { 
return NGX_ERROR,; 


} 
// 必须 返回 


NGX_DONE， 原 因 同 


upstream 
return NGX_DONE,; 
} 





至 此 ， 一 个 使 用 subrequest 的 mytest 模 块 已 经 创建 完成 ， 它 支持 的 并 
发 HTTP 连 接 数 只 与 物理 内 存 大 小 相关 ， 因 此 ， 这 样 的 服务 器 通常 可 以 
轻易 地 支持 几 十 万 的 并 发 TCP 连 接 。 


5.7 ”小 结 





反问 代理 是 Nginx 希 望 实现 的 一 大 功能 。 从 本 章 的 内 容 中 可 以 感受 
到 ，upstream 和 subrequest 都 为 转发 上 游 服 务 器 的 啊 应 做 了 大 量 工作 ， 当 
然 ，upstream 的 转发 过 程 也 非常 高 效 。 然 而 ， 转 发 啊 应 毕竟 只 是 访问 第 
三 方 服务 的 一 种 应 用 ， 而 upstream 最 初始 的 目的 就 是 用 于 访问 上 游 服 务 
侨 。 本 重 前 半 部 分 虽然 以 转发 啊 应 为 例 说 明 了 upstream 的 一 种 使 用 方 
式 ， 但 后 半 部 分 创建 的 子 请 求 却 是 通过 反 同 代理 模块 使 用 upstream 将 上 
游 服务 器 简单 地 保存 在 内 存 中 的 。 关 于 upstream 更 详细 的 用 法 ， 将 在 第 
12 章 讲述 。subrequest 是 分 解 复 杂 请 求 的 设计 方法 ， 派 生出 的 子 请 求 使 
用 某 些 HTTP 模 块 基 于 upstream 访 问 第 三 方 服 务 是 最 常见 的 用 法 。 通 过 
subrequest 可 以 使 Nginx 在 保持 高 并 发 的 前 提 下 处 理 复 杂 的 业务 。 











当 应 用 需要 访问 第 三 方 服务 时 ， 可 以 根据 以 上 特性 选择 使 用 
upstream 或 者 subrequest， 它 们 可 以 完全 地 发 挥 Nginx 原 生 的 高 并 发 特 
性 ， 文 持 现代 互联 网 服务 器 中 海量 数据 的 处 理 。 





第 6 革 开发 一 个 简单 的 HTTP 过 小 模块 


本 章 开始 介绍 如 何 开发 HTTP 过 滤 模 块 。 顾 名 思 义 ，HTTP 过 小 模块 
也 是 一 种 HTTP 模 块 ， 所 以 第 3 章 中 讨论 过 的 如 何 定 义 一 个 HTTP 模 块 以 
及 第 4 章 中 讨论 的 使 用 配置 文件 、 上 下 文 、 日 志 的 方法 对 它 来 说 都 是 适 
用 的 。 事 实 上 ， 开 发 HITP 过 滤 模 块 用 到 的 大 部 分 知识 在 第 3 章 和 第 4 章 
中 都 已 经 介绍 过 了 ， 只 不 过 ，HTTP 过 滤 模 块 的 地 位 、 作 用 与 正常 的 
HTTP 处 理 模 块 是 不 同 的 ， 它 所 做 的 工作 是 对 发 送 给 用 户 的 HITP 响 应 包 
做 一 些 加 工 。 在 6.1 节 和 6.2 节 中 将 会 介绍 默认 编译 进 Nginx 的 官方 HITP 
过 滤 模 块 ， 从 这 些 模块 的 功能 上 就 可 以 对 比 出 HTTP 过滤 模 块 与 HTTP 处 
理 模块 的 不 同 之 处 。HTTP 过 滤 模 块 不 会 去 访问 第 三 方 服务 ， 所 以 第 5 章 
中 介绍 的 upstream 和 subrequest 机 制 在 本 章 中 都 不 会 使 用 到 。 














实际 上 ， 在 阅读 完 第 3 章 和 第 4 章 内 容 后 再 来 学 习 本 章 内 容 ， 相 信 读 
者 会 发 现 开 发 HTTP 过 滤 模 块 是 一 件 非常 简单 的 事情 。 在 6.4 节 中 ， 我 们 
通过 一 个 简单 的 例子 来 演示 如 何 开 发 HITP 过 滤 模 块 。 


6.1 ”过滤 模块 的 意义 





HTTP 过 滤 模 块 与 普通 HITP 模 块 的 功能 是 完全 不 同 的 ， 下 面 先 来 回 


顾 一 下 普通 的 HTTP 模 块 有 何 种 功能 


HTTP 框 架 为 HTTP 请 求 的 处 理 过 程 定 义 了 11 个 阶段 ， 相 关 代 码 如 下 


所 示 : 





typedef enum { 


NGX_HTTP_POST_READ_PHASE = 0, 
NGX_HTTP_SERVER_REWRITE_PHASE， 
NGX_HTTP_FIND_CONFIG_PHASE， 
NGX_HTTP_REWRITE_PHASE， 
NGX_HTTP_POST_REWRITE_PHASE， 
NGX_HTTP_PREACCESS_PHASE, 
NGX_HTTP_ACCESS_PHASE, 
NGX_HTTP_POST_ACCESS_PHASE, 
NGX_HTTP_TRY_FILES_PHASE, 
NGX_HTTP_CONTENT_PHASE, 
NGX_HTTP_LOG_PHASE 














} ngx_http_phases 





HTTP 框 架 人 允许 普通 的 HTTP 处 理 模 块 介 入 其 中 的 7 个 阶段 处 理 请 


求 ， 但 是 通常 大 部 分 HTTP 模 块 〈 官 方 模块 或 者 第 三 方 模块 都 只 在 
NGX_HTTP_CONTENT_PHASE 阶 段 处 理 请 求 。 在 这 一 阶段 处 理 请 求 有 
一 个 特点 ， 即 HTTP 模 块 有 两 种 介入 方法 ， 第 一 种 方法 是 ， 任 一 个 HTTP 
模块 会 对 所 有 的 用 户 请 求 产生 作用 ， 第 二 种 方法 是 ， 只 对 请 求 的 URI 匹 
配 了 nginx.conf 中 某 些 location 表 达 式 下 的 HTTP 模 块 起 作用 。 束 像 第 3 章 
中 定义 的 mytest 模 块 一 样 ， 大 部 分 模块 都 使 用 上 述 的 第 二 种 方法 处 理 请 








求 ， 这 种 方法 的 特点 是 一 种 请 求 仅 由 一 个 HTTP 模 块 〈 在 
NGX_HTTP_CONTENT_PHASE 阶 段 〉 处 理 。 如 果 希 望 多 个 HTTP 模 块 
共同 处 理 一 个 请 求 ， 则 多 半 是 由 subrequest 功 能 来 完成 ， 即 将 原始 请 求 
分 为 多 个 子 请 求 ， 每 个 子 请 求 再 由 一 个 HTTP 模 块 在 
NGX_HTTP_CONTENT_PHASE 阶 段 处 理 。 








然而 ，HTTP 过 滤 模 块 则 不 同 于 此 ， 一 个 请 求 可 以 被 任意 个 HTTP 过 
滤 模 块 处 理 。 因 此 ， 普 通 的 HTTP 模 块 更 倾向 于 完成 请 求 的 核心 功能 ， 
如 static 模 块 负责 静态 文件 的 处 理 。HTTP 过 滤 模 块 则 处 理 一 些 附加 的 功 
能 ， 如 gzip 过 滤 模 块 可 以 把 发 送 给 用 户 的 静态 文件 进行 gzip 压 缩 处 理 后 
再 发 出 去 ，image_filter 这 个 第 三 方 过 滤 模 块 可 以 将 图 片 类 的 静态 文件 制 
作成 缩 略 图 。 而 且 ， 这 些 过 滤 模 块 的 效果 是 可 以 根据 需要 辣 加 的 ， 比 如 
先 由 not_modify 过 滤 模 块 处 理 请 求 中 的 浏览 器 绥 存 信息 ， 再 交 给 range 过 
滤 模 块 处 理 HTTP range 协 议 〈 文 持 断 点 续 传 ) ， 然 后 交 由 gzip 过 滤 模 块 
进行 压缩 ， 可 以 看 到 ， 一 个 请 求 经 由 各 HTTP 过 滤 模 块 流水 线 般 地 依次 
过 傈 处 理 了 下 











HTTP 过 滤 模 块 的 另 一 个 特性 是 ， 在 普通 HTTP 模 块 处 理 请 求 完毕 ， 
并 调用 ngx_http_send_header 发 送 HITTP 头 部 ， 或 者 调用 
ngx_http_output_filter 发 送 HTTP 包 体 时 ， 才 会 由 这 两 个 方法 依次 调用 所 
有 的 HTTP 过 滤 模 块 来 处 理 这 个 请 求 。 因 此 ，HTTP 过 滤 模 块 仅 处 理 服务 
器 发 往 客 户 端的 HITP 响 应 ， 而 不 处 理 客户 端 发 往 服 务 器 的 HITP 请 求 。 


Nginx 明 确 地 将 HTTP 啊 应 分 为 两 个 部 分 : HITP 头 部 和 HTTP 包 体 。 
因此 ， 对 应 的 HTTP 过 滤 模 块 可 以 选择 性 地 只 处 理 HITTP 头 部 或 者 HTTP 
包 体 ， 当 然 也 可 以 二 者 丝 处 理 。 例 如 ，not_modify 过 滤 模 块 只 处 理 HTTP 
头 部 ， 完 全 不 关心 http 包 体 ， 而 gzip 过 滤 模 块 首先 会 处 理 HITTP 头 部 ， 如 
检查 浏览 器 请 求 中 是 否 文 持 gzip 解 压 ， 然 后 检查 啊 应 中 HTTP 头 部 里 的 
Content-Type 是 否 属于 nginx.conf 中 指定 的 gzip 压 缩 类 型 ， 接 着 才 处 理 
HTTP 包 体 ， 针 对 每 一 块 buffer 缓 冲 区 都 进行 gzip 压 缩 ， 这 样 再 交 给 下 一 
个 HTTP 过 滤 模 块 处 理 。 


-> 











6.2 ”过 小 模块 的 调用 顺序 


既然 一 个 请 求 会 被 所 有 的 HTTP 过 滤 模 块 依次 处 理 ， 那 么 下 面 来 看 
一 下 这 些 HTTP 过 小 模块 是 如 何 组 织 到 一 起 的 ， 以 及 它们 的 调用 顺序 是 
如 何 确定 的 。 


6.2.1 ”过渡 链表 是 如 何 构 成 的 


在 编译 Nginx 源 代码 时 ， 已 经 定义 了 一 个 由 所 有 HTTP 过 滤 模 块 组 成 
的 单 链表 ， 这 个 单 链 表 与 一 般 的 链表 是 不 一 样 的 ， 它 有 另类 的 风格 : 链 
表 的 每 一 个 元 素 都 是 一 个 独立 的 C 源 代码 文件 ， 而 这 个 C 源 代码 文件 会 
通过 两 个 static 静 态 指针 《〈 分 别 用 于 处 理 HITP 头 部 和 HTTP 包 体 ) 再 指向 
下 一 个 文件 中 的 过 滤 方 法 。 在 HTTP 框 架 中 定义 了 两 个 指针 ， 指 向 整个 
链表 的 第 一 个 元 素 ， 也 就 是 第 一 个 处 理 HTTP 头 部 、HTTP 包 体 的 方法 。 





这 两 个 处 理 HTTP 头 部 和 HTTP 包 体 的 方法 是 什么 样 的 呢 ? HTTP 框 
架 进 行 了 如 下 定义 : 





typedef ngx_int t (*ngx_http_output_header_filter_pt) 
(ngx_http_request_t *r); 

typedef ngx_int_t (*ngx_http_output_body_filter_pt) 
(ngx_http_request_t *r, ngx_chain_t *chain); 











如 上 所 示 ，ngx_http_output_header _filter_pt 是 每 个 过 滤 模 块 处 理 


HTTP 头 部 的 方法 原型 ， 它 仅 接 收 1 个 参数 r， 也 就 是 当前 的 请 求 ， 其 返 
回 值 一 般 是 与 3.6.1 节 中 介绍 的 返回 码 通用 的 ， 如 NGX_ERROR 表 示 失 
败 ， 而 NGX_OK 表 示 成 功 。 


ngx_http_output body _filter_pt 是 每 个 过 滤 模 块 处 理 HITP 包 体 的 方 
法 原型 ， 它 接收 两 个 参数 一 r 和 chain， 其 中 r 是 当前 的 请 求 ，chain 是 要 发 
送 的 HTTP 包 体 ， 其 返回 值 与 ngx_http_output_header _filter_pt 相 同 。 








所 有 的 HTTP 过 滤 模 块 需要 实现 这 两 个 方法 (或 者 仅 实现 其 中 的 一 
个 也 是 可 以 的 ) 。 因 此 ， 这 个 单 向 链表 是 围绕 着 每 个 文件 〈 也 就 是 
HTTP 过 小 模块 〉 中 的 这 两 个 处 理 方法 来 建立 的 ， 也 就 是 说 ， 链 表 中 的 
元 素 实际 上 砚 是 处 理 方法 。 


先 来 看 一 下 HTTP 框 染 中 定义 的 链表 入 口 : 





extern ngx_http_output_header_filter_pt ngx_http_top_header_ filter; 
extern ngx_http_output_body_filter_pt ngx_http_top_body filter ，; 











当 执 行 ngx_http_send_header 发 送 HTTP 头 部 时 ， 就 从 
ngx_http_top_header filter 指 针 开 始 贺 历 所 有 的 HITP 头 部 过 滤 模 块 ， 而 
在 执行 ngx_http_output_filter 发 送 HTTP 包 体 时 ， 就 从 
ngx_http_top_body_filter 指 针 开 始 壳 历 所 有 的 HITP 包 体 过 滤 模 块 。 下 面 
来 看 一 下 在 Nginx 源 代码 中 是 如 何 做 的 : 





ngx_int_t 
ngx_http_send header(ngx_http_request _t *r) 


if (r->err_status) { 
r->headers out,.status = r->err_status,; 
r->headers_out,.status_line.len = 0; 
} 
return ngx_http_top_header_ filter(r); 
} 








在 发 送 HTTP 头 部 时 ， 从 ngx_http_top_header_filter 指 针 指 向 的 过 滤 
模块 开始 执行 。 而 发 送 HTTP 包 体 时 都 是 调用 ngx_http_output_filter 方 





ngx_int_t 
ngx_http_output_filter(ngx_http_request_t *r, ngx_chain_t *in) 
{ 

ngx_int_t re; 


ngx_connection t *c; 
Cc = r->connection,; 
rc = ngx_http_top_body filter(r, in); 
if (rc == NGX_ERROR) { 
/* NGX_ERROR 可 能 由 任何 过 滤 模 块 返回 





*/ 


} 


return rc; 


c->error = 1; 








裔 历 访 问 所 有 的 HTTP 过 小 模 块 时 ， 这 个 单 链表 中 的 元 素 是 怎么 用 
next 指 针 连 接 起 来 的 呢 ? 很 简单 ， 每 个 HITP 过 滤 模 块 在 初始 化 时 ， 会 
先 找到 链表 的 首 元 素 ngx_http_top_header_filter 指 针 和 
ngx_http_top_body _filter 指 针 ， 再 使 用 static 静 态 类 型 的 
ngx_http_next_header filter 和 ngx_http_next_body_filter 指 针 将 自己 插入 到 
链表 的 首部 ， 这 样 就 行 了 。 下 面 来 看 一 下 在 每 个 过 滤 模 块 中 
ngx_http_next_header filter 和 ngx_http_next_body_filter 指 针 的 定义 : 











static ngx_http_output_header_filter_pt ngx_http_next_header_filter 
static ngx_http_output_body_filter_pt ngx_http_next_body_filter; 














注意 ，ngx_http_next_header_filter 和 ngx_http_next_body_filter 都 必须 
是 static 静 态 变 量 ， 为 什么 呢 ? 因为 static 类 型 可 以 让 上 面 两 个 变量 仪 在 
当前 文件 中 生效 ， 这 就 多 许 所 有 的 HITP 过 滤 模 块 都 有 各 自 的 
ngx_http_next_header_ filter 和 ngx_http_next_body_filter 指 针 。 这 样 ， 在 每 
个 HITP 过 滤 模 块 初 始 化 时 ， 就 可 以 用 上 面 这 两 个 指针 指向 下 一 个 HITP 
过 滤 模 块 了 。 例 如 ， 可 以 像 下列 代 码 一 样 将 当前 HTTP 过 滤 模 块 的 处 理 
方法 添加 到 链表 首部 。 








ngx_http_next_header filter = ngx_http_top_header_ filter 
ngx_http_top_header filter = ngx_http_myfilter_header_filter; 
ngx_http_next_body_filter = ngx_http_top_body_filter， 
ngx_http_top_body_filter = ngx_http_myfilter body filter ， 























这 样 ， 在 初始 化 到 本 模块 时 ， 自 定义 的 
ngx_http_myfilter_header_filter 与 ngx_http_myfilter_body _filter 方 法 就 暂时 
加 入 到 了 链表 的 首部 ， 而 且 本 模块 所 在 文件 中 static 类 型 的 
ngx_http_next_header_ filter 指针 和 ngx_http_next_body_filter 指 针 也 指向 了 
链表 中 原来 的 首部 。 在 实际 使 用 中 ， 如 采 需 要 调用 下 一 个 HITP 过 滤 模 
块 ， 只 需要 调用 ngx_http_next_header_filter(D) 或 者 
ngx_http_next_body_filter(r,chain) 就 可 以 了 。 





6.2.2 ”过 滤 链 表 的 顺序 





HTTP 过 滤 模 块 之 间 的 调用 顺序 是 非常 重要 的 。 如 条 两 个 HITP 过 源 
模块 按照 相反 的 顺序 执行 ， 完 全 可 能 生成 两 个 不 同 的 HTTP 响 应 包 。 例 
如 ， 如 果 现 在 有 一 个 图 片 缩 略图 过 滤 模块 ， 还 有 一 个 图 片 裁剪 过 滤 模 
块 ， 当 返回 一 张 图 片 给 用 户 时 ， 这 两 个 模块 的 执行 顺序 不 同 的 话 就 会 导 
致 用 户 接收 到 不 一 样 的 图 片 。 


在 上 文中 提 到 过 ，Nginx 在 编译 过 程 中 就 会 决定 HTTP 过 滤 模 块 的 顺 
序 。 这 件 事情 到 底 是 怎样 发 生 的 呢 ? 这 其 实 与 3.3 节 中 所 说 的 普通 HITP 
模块 的 顺序 是 一 样 的 ， 也 是 由 configure 生 成 的 ngx_modules 数 组 中 各 模 
块 的 顺序 决定 的 。 





由 于 每 个 HTTP 过 小 模块 的 初始 化 方法 都 会 把 自己 加 入 到 单 链表 的 
首部 ， 所 以 ， 什 么 时 候 、 以 何 种 顺序 调用 这 些 HITP 过 滤 模 块 的 初始 化 
方法 ， 将 会 决定 这 些 HTTP 过 滤 模 块 在 单 链表 中 的 位 置 。 


什么 时 候 开 始 调用 各 个 HTTP 模 块 的 初始 化 方法 呢 ?” 这 主要 取决 于 
我 们 把 类 似 ngx_http_myfilter_init 这 样 的 初始 化 方法 放 到 
ngx_http_module_t 结 构 体 的 哪个 回调 方法 成 员 中 。 例 如 ， 大 多 数 官方 
HTTP 过 小 模块 都 会 把 初始 化 方法 放 到 postconfiguration 指 针 中 ， 那 么 它 
就 会 在 图 4-1 的 第 6 步 将 当前 模块 加 入 到 过 滤 链 表 中 。 不 建议 把 初始 化 方 
法 放 到 ngx_http_module {t 的 其 他 成 员 中 ， 那 样 会 导致 HTTP 过 滤 模 块 的 
顺序 不 可 控 。 


初始 化 时 的 顺序 又 是 如 何 决定 的 呢 ? 首先 回顾 一 下 第 1 章 的 相关 内 
容 ， 在 1.7 节 中 ， 介 绍 了 configure 命 令 生 成 的 ngx_modules.c 文 件 ， 这 个 文 
件 中 的 ngx_modules 数 组 会 保存 所 有 的 Nginx 模 块 ， 包 括 HTTP 普 通 模块 
和 HTTP 过 滤 模 块 ， 而 初始 化 Nginx 模 块 的 顺序 就 是 ngx_modules 数 组 成 
员 的 顺序 。 因 此 ， 只 需要 查看 configure 命 令 生 成 的 ngx_modules.c 文 件 就 
可 以 知道 所 有 HTTP 过 滤 模 块 的 顺序 了 。 





由 此 可 知 ，HTTP 过 小 模块 的 顺序 是 由 configure 命 令 生 成 的 。 当 
然 ， 如 果 用 户 对 configure 命 令 生成 的 模块 顺序 不 满意 ， 完 全 可 以 在 
configure 命 令 执行 后 、make 编 译 命令 执行 前 修改 ngx_modules.c 文 件 的 内 
容 ， 对 ngx_modules 数 组 中 的 成 员 进 行 顺序 上 的 调整 。 


@ ;i 对 于 HTTP 过 滤 模 块 来 说 ， 在 ngx_modules 数 组 中 的 位 置 
越 靠 后 ， 在 实际 执行 请 求 时 就 越 优 先 执行 。 因 为 在 初始 化 HTTP 过 滤 模 
块 时 ， 每 一 个 http 过 滤 模 块 都 是 将 自己 插入 到 整个 单 链表 的 首部 的 。 


configure 执 行 时 是 怎样 确定 Nginx 模 块 间 的 顺序 的 呢 ? 当 我 们 下 载 
官方 提供 的 Nginx 源 代码 包 时 ， 官 方 提 供 的 HITP 过 滤 模 块 顺序 已 经 写 在 
auto 目 录 下 的 modules 脚 本 中 了 。 图 6-1 摘 述 了 这 个 顺序 。 


如 果 在 执行 configure 命 令 时 使 用 --add-module 选 项 新 加 入 第 三 方 的 
HTTP 过 滤 模 块 ， 那 么 第 三 方 过 小 模块 会 处 于 ngx_modules 数 组 中 的 哪个 
位 置 呢 ? 答案 也 可 以 在 图 6-1 中 找到 。 


如 图 6-1 所 示 ， 在 执行 configure 命 令 
了 第 三 方 HTTP 过 滤 模 块 。 


令 时 仅 使 用 --add-module 参 数 添加 
这 里 没有 把 默认 未 编译 进 Nginx 的 官方 HTTP 
过 滤 模 块 考虑 进去 。 这 样 ， 在 configure 执 行 完 毕 后 ，Nginx 各 HTTP 过 波 
模块 的 执行 顺序 就 确定 了 。 





默认 HTTP 过 小 模块 间 的 顺序 必须 如 图 6-1 所 
示 ， 因 为 它们 是 “ 写 死 " 在 auto/modules 脚 本 中 的 。 读 者 可 以 通过 阅读 这 
个 modules 脚 本 的 源 代 码 了 解 Nginx 是 如 何 根据 各 官方 过 滤 模 块 功能 的 不 
同 来 决定 它们 的 顺序 的 。 对 于 图 6-1 中 所 列 的 这 


进行 简单 的 介绍 。 


过 滤 模 块 ， 将 在 下 面 
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图 6-1 默认 即 编 译 进 Nginx 的 官方 HTTP 过 滤 模 块 与 第 三 方 HTTP 过 滤 模 
块 间 的 顺序 


6.2.3 ”官方 默认 HTTP 过 滤 模 块 的 功能 简介 


本 节 介 绍 默认 即 编译 进 Nginx 的 HITP 过 滤 模 块 的 功能 〈 见 表 6- 
1) ， 通 过 对 它们 的 了 解 ， 读 者 就 会 明白 图 6-1 列 出 的 HITP 过 滤 模 块 间 
的 排序 依据 是 什么 。 如 果 用 户 对 configure 命 令 执行 后 的 模块 间 顺 序 不 满 
意 ， 就 可 以 正确 地 修改 这 些 过 滤 模 块 间 的 顺序 。 


表 6-1 默认 即 编译 进 Neinx 的 HITP 过 滤 模 块 


默认 即 编译 进 Nginx 的 HTTP 过 滤 模 块 


ngx_http not modified filter module 


ngx_http_range_body _ filter module 


ngx_http_copy_filter_module 


ngx http_headers filter module 





ngx_http_userid filter module 


ngx_http_charset filter module 


ngx_http_ssi filter module 


ngx_http_postpone filter module 





ngx_http gzip filter module 


ngx_ http_range header filter module 


ngx_http_chunked filter module 


ngx_http_header filter_ module 





ngx_http_write filter module 


功 能 

仅 对 HTTP 头 部 做 处 理 。 在 返回 200 成 功 时 ， 根 据 请 求 中 If-Modified- 
Since 或 者 IEUnmodified-Since 头 部 取得 浏览 器 缓存 文件 的 时 间 ， 再 分 析 
返回 用 户 文件 的 最 后 修改 时 间 ， 以 此 决定 是 和 否 直 接 发 送 304 Not Modified 
响应 给 用 户 

处 理 请 求 中 的 Range 信息 ， 根 据 Range 中 的 要 求 返 回 文件 的 一 部 分 给 
用 户 

仅 对 HTIP 包 体 做 处 理 。 将 用 户 发 送 的 ngx_chain t 结 构 的 HTIP 包 
体 复制 到 新 的 ngx_chain t 结构 中 (都 是 各 种 指针 的 复制 ， 不 包括 实际 
HTTP 响应 内 容 )， 后 续 的 HTTP 过 滤 模 块 处 理 的 ngx_chain t 类 型 的 成 员 
部 是 ngx_http_copy_filter_module 模块 处 理 后 的 变量 

仅 对 HTTP 头 部 做 处 理 。 人 允许 通过 修改 nginx.conf 配置 文件 ， 在 返回 
给 用 户 的 响应 中 添加 任意 的 HTTP 头 部 

仅 对 HTTP 头 部 做 处 理 。 这 就 是 执行 configure 命令 时 提 到 的 http_ 
userid_module 模块 ， 它 基于 cookie 提供 了 简单 的 认证 管理 功能 

可 以 将 文本 类 型 返回 给 用 户 的 响应 包 ， 按 照 nginx.conf 中 的 配置 重新 
进行 编码 ， 再 返回 给 用 户 

支持 SSI ( Server Side Include， 服 务 器 问 戏 人 ) 功能 ， 将 文件 内 容 包 含 
到 网 页 中 并 返回 给 用 户 

仅 对 HTTP 包 体 做 处 理 。5.5.2 节 详 细 介 绍 过 该 过 滤 模 块 。 它 仅 应 用 于 
subrequest 产生 的 子 请 求 。 它 使 得 多 个 子 请 求 同 时 向 客户 端 发 送 响 应 时 能 
够 有 序 ， 所 谓 的 “有 序 ” 是 指 按照 构造 子 请 求 的 顺序 发 送 响 应 

对 特定 的 HTTP 响应 包 体 (如 网 页 或 者 文本 文件 ) 进行 gzip 压缩 ， 再 
把 压缩 后 的 内 容 返 回 给 用 户 

支持 range 协议 

支持 chunk 编码 

仅 对 HTTP 头 部 做 处 理 。 该 过 滤 模 块 将 会 把 r>headers_out 结 构 体 
中 的 成 员 序 列 化 为 返回 给 用 户 的 HTTP 响应 字符 流 ， 包 括 响应 行 (如 
HTTP/1.1 200 OK) 和 了 啊 应 头 部 ， 并 通过 调用 ngx http_ write filter _ 
module 过 滤 模 块 中 的 过 滤 方 法 直接 将 HTTP 包头 发 送 到 客户 端 

仅 对 HTTP 包 体 做 处 理 。 该 模块 负责 向 客户 端 发 送 HTTP 响应 





从 表 6-1 中 可 以 了 解 到 这 些 默 认 的 HTTP 过 滤 模 块 为 什么 要 以 图 6-1 的 
顺序 排列 ， 同 样 可 以 弄 清楚 第 三 方 过 小 模 块 为 何 要 在 
ngx_http_headers_filter_module 模 块 之 后 、ngx_http_userid_filter_module 


模块 之 前 。 





在 开发 HTTP 过 滤 模 块 时 ， 如 果 对 configure 执 行 后 的 过 滤 模 块 顺序 


不 满意 ， 那 么 在 修改 ngx_modules.c 文 件 时 先 要 对 照 表 6-1 看 一 下 每 个 模 
块 的 功能 是 否 符合 它 的 位 置 。 


6.3 ” HTTP 过 滤 模 块 的 开发 步 又 


HTTP 过 滤 模 块 的 开发 步 又 与 第 3 章 中 所 述 的 普通 HTTP 模 块 的 开发 
步骤 基本 一 致 ， 这 里 再 简要 地 概括 一 下 ， 即 如 下 8 个 步骤 : 


1) 确定 源 代 码 文件 名 称 。 通 常 ，HTTP 过 滤 模 块 的 功能 都 比较 单 
， 因 此 ， 一 般 1 个 C 源 文件 就 可 以 实现 1 个 HTTP 过 滤 模 块 。 由 于 需要 将 
源 文 件 加 入 到 Makefile 中 ， 因 此 这 时 就 要 确定 好 源 文件 名 称 。 当 然 ， 用 
多 个 C 源 文件 甚至 C++ 源 文件 实现 1 个 HTTP 过 滤 模 块 也 是 可 以 的 ， 可 参 
考 3.3 节 和 3.9 节 ， 这 里 不 再 资 述 


2) 在 源 代 码 所 在 目录 创建 config 脚 本 文件 ， 当 执行 configure 时 将 该 
目录 添加 进去 。config 文 件 的 编写 方法 与 3.3.1 节 中 开发 普通 HTTP 模块 时 
介绍 的 编写 方法 基本 一 致 ， 唯 一 需要 改变 的 是 ， 把 HITP_MODULES 变 
量 改 为 HTTP_FILTER_MODULES 变 量 ， 这 样 才 会 把 我 们 的 模块 作为 
HTTP 过 小 模块 ， 并 把 它 放 置 到 正确 的 位 置 〈( 图 6-1 所 示 的 第 三 方 过 滤 模 
块 位 置 ) 上 。 








在 执行 configure 命 令 时 ， 其 编译 方法 与 3.3.2 节 中 介绍 的 是 一 样 的 。 
在 执行 configure--add-module=PATH 时 ，PATH 就 是 HTTP 过 滤 模 块 源 文 
件 所 在 的 路 径 。 当 多 个 源 代码 文件 实现 1 个 HTTP 过 小 模块 时 ， 需 在 
NGX_ADDON_SRCS 变 量 中 添加 其 他 源 代 码 文件 。 


3) 定义 过 滤 模 块 。 实 例 化 ngx_module_t 类 型 的 模块 结构 ， 这 与 3.4 

介绍 的 内 容 类 似 ， 同 时 可 以 参考 3.5 节 中 的 例子 。 因 为 HTTP 过 滤 模 块 

也 是 HTTP 模 块 ， 所 以 在 定义 ngx_module t 结 构 时 ， 其 中 的 type 成 员 也 是 
NGX_HTIP_ MODULE。 这 一 步骤 与 定义 普通 的 HITP 模 块 是 相同 的 。 


4) 处 理 感 兴趣 的 配置 项 。 依 照 第 4 章 中 介绍 的 方法 ， 可 通过 设置 
ngx_module t 结 构 中 的 ngx_command t 数 组 来 处 理 感 兴趣 的 配置 项 。 





5) 实现 初始 化 方法 。 初 始 化 方法 就 是 把 本 模块 中 处 理 HITP 头 部 的 
ngx_http_output_header filter_pt 方 法 与 处 理 HTTP 包 体 的 
ngx_http_output_body_filter_pt 方 法 插入 到 过 滤 模 块 链 表 的 首部 ， 

6.2.1 市 中 的 例子 。 


6) 实现 处 理 HITP 头 部 的 方法 。 实 现 
ngx_http_output_header _filter_pt 原 型 的 方法 ， 用 于 处 理 HITP 头 部 ， 如 下 
所 示 : 





typedef ngx_int_t (*ngx_http_output_header_ filter pt) (ngx_http_request t *r); 








一 定 要 在 模块 初始 化 方法 中 将 其 添加 到 过 滤 模 块 链表 中 。 


7) 实现 处 理 HTTP 包 体 的 方法 。 实 现 ngx_http_output_body_filter_pt 
原型 的 方法 ， 用 于 处 理 HITP 包 体 ， 如 下 所 示 : 





typedef ngx_int t (*ngx_http_output_body_filter_pt) (ngx_http_request _t *r ngx_chaji 





一 定 要 在 模块 初始 化 方法 中 将 其 添加 a 到 过 小 模块 链表 中 。 





8) 编译 安装 后 ， 修 改 nginx.conf 文 件 并 启动 自 定义 过 滤 模 块 。 通 
常 ， 出 于 灵活 性 考虑 ， 在 配置 文件 中 都 会 有 配置 项 决定 是 否 启动 模块 。 
因此 ， 执 行 make 编 译 以 及 make install 安 装 后 ， 再 修改 nginx.conf 文 件 中 
的 配置 项 ， 自 定义 过 滤 模 块 的 功能 。 











6.4 HTTP 过 滤 模 块 的 简单 例子 


本 节 通 过 一 个 简单 的 例子 来 说 明 如 何 开发 HITP 过 滤 模 块 。 场 景 是 
这 样 的 ， 用 户 的 请 求 由 static 静 态 文 件 模块 进行 了 处 理 ， 它 会 根据 URI 返 
回 磁盘 中 的 文件 给 用 户 。 而 我 们 开 肥 的 过 滤 模 块 就 会 在 返回 给 用 户 的 啊 
应 包 体 前 加 一 段 字 符 串 : "[my filter prefixJ"。 逢 要 实现 的 功能 束 是 这 么 
人 简单， 当然 ， 可 以 在 配置 文件 中 决定 是 人 否 开 局 此 功能 。 








图 6-2 简 单 地 描绘 了 处 理 HITTP 头 部 的 方法 将 会 执行 的 操作 ， 而 图 6-3 
则 是 处 理 HITP 包 体 的 方法 将 会 执行 的 操作 。 














今 查 是 否 向 客户 端 返回 200 


[返回 200 表 示 成 功 ] 


检查 配置 文件 中 是 否 开启 功能 


检查 Content -Type 是 否 是 文本 类 型 


[ 包 体 的 类 型 是 文本 文件 ] 


设置 HTTP 上下文 表示 当前 请 求 的 响应 包 体 时 
要 加 前 绥 





执行 下 一 个 过 滤 模 块 的 HTTP 


[返回 非 200] 


图 6-2 ”过 滤 模 块 例子 中 ，HTIP 头 部 处 理 方 法 的 执行 活动 图 


与 图 6-2 相 关 的 代码 可 参见 6.4.5 节 。 


检查 HTTP 上 下 文中 是 否 表 示 要 加 前 级 






[上 下 文中 显示 需要 处 理 的 包 体 ] ER 
| 不 击 呢 处 理 包 体 | 


在 当前 竺 发 送 的 HTTP 包 体 前 添加 月 


执行 下 一 个 过 滤 模 块 的 HTTP 包 体 过 滤 方 法 


图 6-3” 过滤 模 块 例子 中 ，HTTP 包 体 处 理 方 法 的 执行 活动 图 
与 图 6-3 相 关 的 代码 可 参见 6.4.6 节 。 


由 于 HTTP 过 滤 模 块 也 是 一 种 HTTP 模 块 ， 所 以 大 家 会 发 现 本 章 
myfilter 过 小 模块 的 代码 与 第 3 间 介 绍 的 例子 中 的 代码 很 相似 。 


6.4.1 ”如 何 编写 config 文 件 


可 以 仅 用 1 个 源 文件 实现 上 述 HTTP 过 滤 模 块 ， 源 文件 名 为 
ngx_http_myfilter_ module.c。 在 该 文件 所 在 目录 中 添加 config 文 件 ， 其 内 
容 如 下 : 





ngx_addon_name=ngx_http_myfilter_module 
HTTP_FILTER_MODULES="$HTTP_FILTER_MODULES ngx_http_myfilter_module" 
NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_myfilter_module.c" 





将 模块 名 添加 到 HTTP_FILTER_MODULES 变 量 后 ，auto/modules 脚 
本 就 会 按照 6.2.2 节 中 定义 的 顺序 那样 ， 将 ngx_http_myfilter_ module 过 滤 
模块 添加 到 ngx_modules 数 组 的 合适 位 置 上 上。 其中， 

NGX_ADDON_SRCS 定 义 的 是 竺 编译 的 C 源 文件 。 


6.4.2 ”配置 项 和 上 下 文 


首先 希望 在 nginx.conf 中 有 一 个 控制 当前 HTTP 过 滤 模 块 是 否 生 效 的 
配置 项 ， 它 的 参数 值 为 on 或 者 off， 分 别 表示 开启 或 者 关闭 。 因 此 ， 按 照 
第 4 章 介 绍 的 用 法 ， 需 要 建立 ngx_http_myfilter_conf_t 结 构 体 来 存储 配置 
项 ， 其 中 使 用 ngx_flag_t 类 型 的 enable 变 量 来 存储 这 个 参数 值 ， 如 下 所 


人 外: 








typedef struct { 
ngx_flag_t enable; 
} ngx_http_myfilter_conf_t; 








同样 ， 下 面 实现 的 ngx_http_myfilter_create_conf 用 于 分 配 存储 配置 


项 的 结构 体 ngx_http_myfilter_conf t: 





static void* ngx_http_myfilter_create conf(ngx_conf_t *cf) 


{ 
ngx_http_myfilter_conf t *mycf; 
// 创建 存储 配置 项 的 结构 体 


mycf = (ngx_http_myfilter_conf t *)ngx_pcalloc(cf->pool, sizeof(ngx_http_myfilt 
if (mycf == NULL) { 
return NULL; 


} 
// ngx_flat_t 类 型 的 变量 。 如 果 使 用 预 设 函 数 


ngx_conf_set_flag_slot 解 析 配 置 项 和 参数， 那么 必须 初始 化 为 





NGX_CONF_UNSET 
mycf->enable= NGX_CONF_UNSET 
return mycf， 





就 像 gzip 等 其 他 HTTP 过 滤 模 块 的 配置 项 一 样 ， 我 们 往往 会 允许 配 
置 项 不 只 出 现在 location{.…} 配 置 块 中 ， 还 可 以 出 现在 server{…} 或 者 
http{.….} 配 置 块 中 ， 因 此 ， 还 需要 实现 一 个 配置 项 值 的 合并 方法 一 一 
ngx_http_myfilter_merge_conf， 代 码 如 下 所 示 : 











static char * 
ngx_http_myfilter_merge_ conf(ngx_conf_t *cf, void *parent, void *child) 


ngx_http_myfilter_conf_t *prev 
ngx_http_myfilter_conf_t *conf 
// 合并 


(ngx_http_myfilter_conf_t *)parent ， 
(ngx_http_myfilter_conf t *)child; 


ngx_flat_t 类 型 的 配置 项 


enable 
ngx_conf_merge_value(conf->enable, prev->enable, 0); 
return NGX_CONF_OK,; 


} 


= 


根据 6.4.3 节 中 介绍 的 配置 项 名 称 可 知 ， 在 nginx.conf 配 置 文件 中 需 
要 有 “add_prefix on;” 字 样 的 配置 项 。 


再 建立 一 个 HTTP 上 下 文 结构 体 ngx_http_myfilter_ctx_t， 其 中 包括 
add_prefix 整 型 成 员 ， 在 处 理 HTTP 头 部 时 用 这 个 add_prefix 表 示 在 处 理 
HTTP 包 体 时 是 人 否 添加 六 绥 。 





typedef struct { 
ngx_int_t add_prefix; 
} ngx_http_myfilter_ctx_t; 





当 add_prefix 为 0 时 ， 表 示 不 需要 在 返回 的 包 体 前 加 前 级 ;， 当 
add_prefix 为 1 时 ， 表 示 应 当 在 包 体 前 加 前 级 ; ， 当 add_prefix 为 2 时 ， 表 示 
已 经 添加 过 前 缀 了 。 为 什么 add_prefixz 有 3 个 值 呢 ? 因为 HTTP 头 部 处 理 
方法 在 1 个 请 求 中 只 会 被 调用 1 次 ， 但 包 体 处 理 方法 在 1 个 请 求 中 是 有 可 
能 被 多 次 调用 的 ， 而 实际 上 我 们 只 和 希望 在 包头 加 1 次 前 缀 ， 因 此 
add_prefix 制 定 了 3 个 值 。 





6.4.3 定义 HTTP 过 滤 模 块 


定义 ngx_module_t 模 块 前 ， 需 要 先 定义 好 它 的 两 个 关键 成 员 : 


ngx_command_t 类 型 的 commands 数 组 和 ngx_http_module_t 类 型 的 ctx 成 


3 


下 面 定义 了 ngx_http_myfilter_commands 数 组 ， 它 会 处 理 add_prefix 


配置 项 ， 将 配置 项 参数 解析 到 ngx_http_myfilter_conf_t 上 下 文 结构 体 的 
enable 成 员 中 。 





static ngx_command t ngx_http_myfilter_commands[] = { 

{ ngx_string("add_prefix"), 
NGX_HTTP_MAIN_CONF |NGX_HTTP_SRV_CONF |NGX_HTTP_LOC_CONF|NGX_HTTP_LM] 
ngx_conf_set_flag_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_myfilter_conf_t, enable), 
NULL }, 

ngx_null command 








}; 





在 定义 ngx_http_module_t 类 型 的 ngx_http_myfilter_module_ctx 时 ， 
需要 将 6.4.2 节 中 定义 的 ngx_http_myfilter_create_conf 回 调 方法 放 到 
create_loc_conf 成 员 中 ， 而 ngx_http_myfilter_merge_conf 回 调 方法 则 要 放 
到 merge_loc_conf 成 员 中 。 男 外 ， 在 6.4.4 节 中 定义 的 
ngx_http_myfilter_init 模 块 初始 化 方法 也 要 放 到 postconfiguration 成 员 中 ， 
表示 当 读 取 完 所 有 的 配置 项 后 就 会 回调 ngx_http_myfilter_init 方 法 ， 代 码 
如 下 所 示 : 








static ngx_http_module t ngx_http_myfilter module ctx = { 





NULL, /* preconfiguration 方 法 
*/ 

ngx_http_myfilter_init, /* postconfiguration 方 法 
*/ 

NULL, /* create_main_conf 方 法 
*/ 

NULL, /* init_main_conf 方 法 
*/ 


NULL， /* create_srv_conf 方 法 


x/ 
NULL， 


*/ 


/* merge_srv_conf 方 法 


ngx_http_myfilter_create_conf,/* create_loc_conf 方 法 


A 


ngx_http_myfilter_merge_conf 


*/ 
}; 


/* merge_loc_conf 方 法 





有 了 ngx_command_t 类 


型 的 commands 数 组 和 ngx_http_module_t 类 型 


的 ctx 成 员 后 ， 下 面 就 可 以 定义 ngx_http_myfilter_module 过 滤 模 块 了 。 





ngx_module t ngx_http_myfilter module = { 





NGX_MODULE_V1, 


&ngx_http_myfilter_module_ctx, 


ngx_http_myfilter_commands, 

NGX_HTTP_MODULE, 

NULL, 

NULL, 

NULL, 

NULL, 

NULL, 

NULL, 

NULL, 

NGX_MODULE_V1_PADDING 
}; 


/* module context */ 


/* module directives */ 
module type */ 


init 
init 
init 
init 
exit 
exit 
exit 


master */ 
module */ 
process */ 
thread */ 
thread */ 
process */ 
master */ 





它 的 类 型 仍然 是 NGX_HTTP MODULE。 


6.4.4 初始 化 HTTP 过 滤 模 块 





在 定义 ngx_http_myfilter_init 方 法 时 ， 首 先 需 要 定义 静态 指针 


ngx_http_next_header_filter， 用 于 指 癌 下 一 个 过 


才 滤 模块 的 HITTP 头 部 处 理 


方法 ， 然 后 要 定义 静态 指针 ngx_http_next_body_filter， 用 于 指向 下 一 个 


过 小 模块 的 HTTP 包 体 处 理 方法 ， 代 码 如 下 所 示 。 








static ngx_http_output_header_filter_pt ngx_http_next_header_filter; 
static ngx_http_output_body_filter_pt ngx_http_next_body_filter; 
static ngx_int_t ngx_http_myfilter_init(ngx_conf_t *cf) 











// 插入 到 头 部 处 理 方法 链表 的 首部 


ngx_http_next_header filter = ngx_http_top_header_ filter; 
ngx_http_top_header_filter = ngx_http_myfilter_header_filter; 
// 插入 到 包 体 处 理 方法 链表 的 首部 











ngx_http_next_body_filter = ngx_http_top_body_filter,; 
ngx_http_top_body_filter = ngx_http_myfilter_body_filter; 
return NGX_OK， 














6.4.5 ”处理 请 求 中 的 HITP 头 部 


我 们 需要 把 在 HITP 啊 应 包 体 前 加 的 字符 串 前 绥 便 编 但 为 
filter_prefix 变 量 ， 如 下 所 示 。 





static ngx_str_t filter_prefix = ngx_string("[my filter prefix]"); 





根据 图 6-2 中 描述 的 处 理 流程 ，ngx_http_myfilter_header_filter 回 调 
方法 的 实现 应 如 下 所 示 。 











static ngx_int_t 
ngx_http_myfilter_header_filter(ngx_http_request_t *r) 
{ 


ngx_http_myfilter_ctx_t “OEX’ 


ngx_http_myfilter_conf_t *conf; 
/* 如 果 不 是 返回 成 功 ， 那 么 这 时 是 不 需要 理会 是 否 加 前 级 的 ， 直 接 交 由 下 一 个 过 滤 模 块 处 理 响应 码 非 


200 的 情况 


if (r->headers out.status != NGX_HTTP_OK) { 
return ngx_http_next_header_filter(r); 





HTTP 上 下 文 


ctx = ngx_http_get module ctx(r, ngx_http_myfilter_module); 
if (ctx) { 
/* 该 请 求 的 上 下 文 已 经 存在 ， 这 说 明 





ngx_http_myfilter_header_filter 已 经 被 调用 过 


1 次 ， 直 接 交 由 下 一 个 过 滤 模 块 处 理 


2 
return ngx_http_next_header_ filter(r); 





} 
// 获取 存储 配置 项 的 


ngx_http_myfilter_conf_t 结 构 体 


conf = ngx_http_get_ module_ loc conf(r, ngx_http_myfilter_module); 
/* 如 果 





enable 成 员 为 


9， 也 就 是 配置 文件 中 没有 配置 


add_prefix 配 置 项 ， 或 者 


add_prefix 配 置 项 的 参数 值 是 


off， 那 么 这 时 直接 交 由 下 一 个 过 滤 模 块 处 理 


*/ 
if (conf->enable == 0) { 
return ngx_http_next_header filter(r); 





} 
// 构造 


HTTP 上 下 文 结构 体 


ngx_http_myfilter_ctx_t 
ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_myfilter_ctx_t)); 
if (ctx == NULL) { 
return NGX_ERROR; 
} 
// add_prefix 为 


0 表示 不 加 前 级 


ctx->add_prefix = 0; 
// 将 构造 的 上 下 文 设置 到 当前 请 求 中 


ngx_http_set_ctx(r, ctx, ngx_http_myfilter_module); 
// myfilter 过 滤 模块 只 处 理 


Content -Type 是 “ 
text/plain” 类 型 的 


HTTP 响 应 


If (r->headers out.content_type.len >= sizeof("text/plain") - 1 

&& Ngx_strncasecmp(r->headers out.content_type.data, (u_char *) "text/plain",sizeof! 
// 设置 为 

1 表示 需要 在 


HTTP 包 体 前 加 入 前 级 


ctx->add_prefix = 1; 
/* 当 处 理 模 块 已 经 在 


Content-Length 中 写 入 了 
HTTP 包 体 的 长 度 时 ， 由 于 我 们 加 入 了 前 组 字符 串 ， 所 以 需要 把 这 个 字符 串 的 长 度 也 加 入 到 
Content -Length 中 


*/ 
If (r->headers out.content_ length n > 0) 


r->headers_out,content_Jength_n += filter_prefix,.len; 


} 
// 交 由 下 一 个 过 滤 模 块 继续 处 理 


return ngx_http_next_header filter(r); 











注意 ， 除 非 出 现 了 严重 的 错误 ， 一 般 情 况 下 都 需要 交 由 下 一 个 过 滤 
模块 继续 处 理 。 究 竟 是 在 ngx_http_myfilter_header_ filter 函数 中 直接 返回 
NGX_ERROR， 还 是 调用 ngx_http_next_header_filter(7) 继 续 处 理 ， 读 者 
可 以 参考 6.2.3 市 中 介绍 的 一 些 必需 的 过 小 模 块 具备 的 功能 来 决定 。 


6.4.6 ”处 理 请 求 中 的 HTTP 包 体 


根据 图 6-3 中 摘 述 的 处 理 流 程 看 ，ngx_http_myfilter_ body_filter 回 调 
方法 的 实现 应 如 下 所 示 。 











static ngx_int_ 
ngx_http_myfilter_body_filter(ngx_http_request t *r, ngx_chain t *in) 


ngx_http_myfilter_ctx_t CE 
ctx = ngx_http_get module ctx(r, ngx_http_myfilter_module); 
/* 如 果 获 取 不 到 上 下 文 ， 或 者 上 下 文 结 构 体 中 的 





add_prefix 为 


0 或 者 


2 时 ， 都 不 会 添加 前 级 ， 这 时 直接 交 给 下 一 个 


HTTP 过 滤 模块 处 理 


Wy4 
if (ctx == NULL || ctx->add prefix != 1) { 
return ngx_http_next_body_filter(r, in); 





add_prefix 设 置 为 


2， 这 样 即 使 


ngx_http_myfilter_body_filter 再 次 回调 时 ， 也 不 会 重复 添加 前 级 





*/ 
ctx->add_prefix = 2; 
// 从 请 求 的 内 存 池 中 分 配 内 存 ， 用 于 存储 字符 串 前 缓 


ngx_buf_t* b = ngx_create temp_buf(r->pool, filter_prefix.1len); 
// 将 


ngx_buf_t 中 的 指针 正确 地 指向 


filter_prefix 字 符 事 


b->start = b->pos = filter_prefix.data; 
b->last = b->pos + filter_prefix.len; 
/* 从 请 求 的 内 存 池 中 生成 


ngx_chain_t 链 表 ， 将 刚 分 配 的 
ngx_buf_t 设 置 到 

buf 成 员 中 ， 并 将 它 添加 到 原先 待 发 送 的 
HTTP 包 体 前 面 


*/ 

ngx_chain_t *cl = ngx_alloc_chain_link(r->pool); 
cl->buf = b; 

cl->next = in; 

// 调用 下 一 个 模块 的 


HTTP 包 体 处 理 方法 ， 注 意 ， 这 时 传 入 的 是 新 生成 的 


C1 链表 





return ngx_http_next_body_filter(r, cl1); 
} 





到 此 ， 一 个 简单 的 HTTP 过 小 模块 束 开 及 完成 了 。 无 论 功 能 多 么 复 
杂 的 HTTP 过 小 模块 ， 一 样 可 以 从 这 个 例子 中 衍生 出 来 。 


6.5 ”小 结 








过 本 章 的 学 习 ， 读 者 应 该 已 经 掌握 如 何 编写 HTTP 过 滤 模 块 了 。 
相 比 普通 的 HTTP 处 理 模 块 ， 编 写 HTTP 过 滤 模 块 要 简单 许多 ， 因 为 它 不 
可 能 去 访问 第 三 方 服 务 ， 也 不 负责 发 送 啊 应 到 客户 闹 。HTTP 过 小 模块 
的 优势 在 于 闭 加 ， 即 1 个 请 求 可 以 被 许多 HTTP 过 滤 模 块 处 理 ， 这 种 设计 
带 来 了 很 大 的 灵活 性 。 读 者 在 开发 HTTP 过 滤 模 块 时 ， 也 要 把 模块 功能 
分 解 得 更 单一 一 些 ， 即 在 功能 过 于 复杂 时 应 该 分 成 多 个 HTTP 过 滤 模 块 
来 实现 。 


第 7 草 Nginx 提 供 的 高 级 数据 结构 


任何 复杂 的 程序 都 需要 用 到 数组 、 链 表 、 树 等 数据 结构 ， 这 些 容器 
可 以 让 用 户 忽略 底层 细节 ， 人 快速 开发 出 各 种 高 级 数据 结构 、 实 现 复杂 的 
业务 功能 。 在 开发 Nginx 模 块 时 ， 同 样 也 需要 这 样 的 高 级 通用 容器 。 然 
而 ，Nginx 有 两 个 特点 : 跨 平 台 、 使 用 C 语 言 实现 ， 这 两 个 特点 导致 
Nginx 不 宜 使 用 一 些 第 三 方 中 间 件 提 供 的 容器 和 算法 。 路 平台 意味 着 
Nginx 必 须 可 以 运行 在 Windows、Linux 等 许多 主流 操作 系统 上 ， 因 此 ， 
Nginx 的 所 有 代码 都 必须 可 以 跨 平 台 编 译 、 运 行 。 另 外 ，Nginx 是 由 C 语 
言 开 发 的 。 虽 然 所 有 的 操作 系统 都 支持 C 语 言 ， 但 是 C 语 言 与 每 一 个 操 
作 系 统 都 是 强 相 关 的 ， 且 C 库 对 操作 系统 的 茶 些 系统 调用 封装 的 方法 并 
不 是 跨 平台 的 。 

















对 于 这 种 情况 ，Nginx 的 解决 方法 很 简单 ， 在 这 些 必 须 特 殊 化 处 理 
的 地 方 ， 对 每 个 操作 系统 都 给 一 份 特异 化 的 实现 ， 因 此 ， 用 户 在 下 载 
Nginx 源 码 包 时 会 发 现 有 Windows 版 本 和 UNIX 版 本 。 而 对 于 基础 的 数据 
结构 和 算法 ，Nginx 则 完全 从 头 实现 了 一 忆 ， 如 动态 数组 、 链 表 、 二 又 
排序 树 、 散 列表 等 。 当 开发 功能 复杂 的 模块 时 ， 如 果 需 要 使 用 这 些 数据 
结构 ， 不 妨 使 用 它们 来 加 快 开 发 速度 ， 这 些 数据 结构 的 好 处 是 完全 使 用 
C 语 言 从头 实 现 ， 运 行 效率 非常 高 ， 而 且 它们 是 可 以 跨 平 台 使 用 的 ， 在 
主流 操作 系统 上 都 可 以 正常 的 工作 。 





当然 ， 由 于 这 些 基 础 数据 结构 的 路 平台 特性 、C 语 言 面 癌 过 程 的 特 
扩 、 不 统一 的 使 用 风格 以 及 几乎 没有 注释 的 Nginx 源 代码 ， 造 成 了 它们 
并 不 容易 使 用 ， 本 章 将 会 详细 阐述 它们 的 设计 目的 、 思 想 、 使 用 方法 ， 
并 通过 例子 形象 地 展示 这 些 容 器 的 使 用 方式 。 


7.1 Nginx 提 供 的 高 级 数据 结构 概述 


本 章 将 介绍 Nginx 实 现 的 6 个 基本 容器 ， 熟 练 使 用 这 6 个 基本 容器 ， 
将 会 大 大 提高 开 太 Nginx 模 块 的 效率 ， 也 可 以 更 加 方便 地 实现 复杂 的 功 








ngx_queue_t 双 辣 链 表 是 Nginx 提 供 的 轻 量 级 链表 容器 ， 它 与 Nginx 的 
内 存 池 无 天 ， 因 此 ， 这 个 链表 将 不 会 负 员 分 配 内 存 来 存放 链表 元 素 。 这 
意味 着 ， 任 何 链表 元 素 都 需要 通过 其 他 方式 来 分 配 它 所 需要 的 内 存 空 
间 ， 不 要 指望 ngx_queue_t 帮 助 存 储 元 素 。ngx_queue_t 只 是 把 这 些 已 经 
分 配 好 内 存 的 元 素 用 双 癌 链表 连接 起 来 。ngx_queue_t 的 功能 虽然 很 简 
单 ， 但 它 非常 轻 量 级 ， 对 每 个 用 户 数 据 而 言 ， 只 需要 增加 两 个 指针 的 空 
间 即 可 ， 消 耗 的 内 存 很 少 。 同 时 ，ngx_queue_t 还 提供 了 一 个 非常 简易 的 
插入 排序 法 ， 虽 然 不 太 适 合 超大 规模 数据 的 排序 ， 但 它 胜 在 简单 实用 。 
ngx_queue_t 作 为 C 语 言 提 供 的 通用 双向 链表 ， 其 设计 思路 值得 用 户 参 
考 。 














ngx_array_t 动 态 数组 类 似 于 C++ 语言 STL 库 的 vector 容 器 ， 它 用 连续 
的 内 存 存 放 着 大 小 相同 的 元 素 〈 就 像 数组 ) ， 这 使 得 它 按照 下 标 检 索 数 
据 的 效率 非常 高 ， 可 以 用 O(1) 的 时 间 来 访问 随机 元 素 。 相 比 数组 ， 它 的 
优势 在 于 ， 数 组 通常 是 固定 大 小 的 ， 而 ngx_array_t 可 以 在 达到 容量 最 大 








值 时 目 动 扩 容 〈 扩 容 算法 与 常见 的 vector 容 露 不同) 。ngx_array_t 与 
ngx_queue_t 的 一 个 显著 不 同 点 在 于 ，ngx_queue_t 并 不 负责 为 容 右 元 系 
分 配 内 存 ， 而 ngx_array_t 是 负责 容 髓 元 素 的 内 存 分 配 的 。ngx_array_t 也 
契 Nginx 中 应 用 非常 广泛 的 数据 结构 ， 本 章 介 绍 的 文 持 通 配 符 的 散 列 表 
中 就 有 使 用 它 的 例子 。 

















ngx_list_t 单 向 链表 与 ngx_queue_{t 双 向 链表 是 完全 不 同 的 ， 它 是 负责 
容 需 内 元 素 内 存 分 配 的 ， 因 此 ， 这 两 个 容 需 在 通用 性 的 设计 思路 上 是 完 
全 不 同 的 。 同 时 它 与 ngx_array_t 也 不 一 样 ， 它 不 是 用 完全 连续 的 内 存 来 
存储 元 素 ， 而 是 用 单 链表 将 多 段 内 存 块 连接 起 来 ， 每 段 内 存 块 也 存储 了 
多 个 元 素 ， 有 点 像 “ 数 组 + 单 链表 ”。 在 3.2.3 节 中 已 经 详细 介绍 过 
ngx_list_t 单 问 链 表 ， 本 章 不 再 费 述 。 

















ngx_rbtree {《〈 红 黑 树 ) 是 一 种 非常 有 效 的 高 级 数据 结构 ， 它 在 许多 
系统 中 都 作为 核心 数据 结构 存在 。 它 在 检索 特定 关键 字 时 不 再 需要 像 以 
上 容器 那样 遍历 容器 ， 同 时 ，ngx_rbtree_t 容 器 在 检索 、 插 入 、 删 除 元 素 
方面 非常 高 效 ， 且 其 针对 各 种 类 型 的 数据 的 平均 时 间 都 很 优异 。 与 散 列 
表 相 比 ，ngx_rbtree_t 还 支持 范围 查询 ， 也 支持 高 效 地 遍历 所 有 元 素 ， 因 
此 ，Nginx 的 核心 模块 是 离 不 开 ngx_rbtree_t 容 器 的 。 同 时 ， 一 些 较 复杂 
的 Nginx 模 块 也 都 用 到 了 ngx_rbtree_t 容 器 。 用 户 在 需要 用 到 快速 检索 的 
容器 时 ， 应 该 痛 完 考虑 是 不 是 使 用 ngx_rbtree_t。 











ngx_radix_tree_t 基 数 树 与 ngx_rbtree_t 红 黑 树 一 样 都 是 二 又 查找 树 ， 


ngx_rbtree_t 红 黑 树 具备 的 优点 ，ngx_radix_tree_t 基 数 树 同样 也 有 ， 但 
ngx_radix_tree_t 基 数 树 的 应 用 范围 要 比 ngx_rbtree_t 红 黑 树 小 ， 因 为 
ngx_radix_tree_t 要 求 元 素 必 须 以 整 型 数据 作为 关键 字 ， 所 以 大 大 减少 了 
它 的 应 用 场景 。 然 而 ， 由 于 ngx_radix_tree_t 基 数 树 在 插入 、 删 除 元 素 时 
不 需要 做 旋转 操作 ， 因 此 它 的 插入 、 删 除 效 率 一 般 要 比 ngx_rbtree_t 红 黑 
树 高 。 选 择 使 用 哪 种 二 又 查找 树 取决 于 实际 的 应 用 场景 。 不 过 ， 
ngx_radix_tree_t 基 数 树 的 用 法 要 比 ngx_rbtree_t 红 黑 树 简单 许多 。 


支持 通配符 的 散 列 表 是 Nginx 独 创 的 。Nginx 首 先 实 现 了 基础 的 第 用 
散 列表 ， 在 这 个 基础 上 ， 它 又 根据 Web 服 务 器 的 特点 ， 对 于 URI 域 名 这 
种 场景 设计 了 文 持 通配符 的 散 列表 ， 当 然 ， 只 支持 前 置 通配符 和 后 置 通 
配 符 ， 如 www.test.* 和 *.test.com。Nginx 对 于 这 种 散 列 表 做 了 非常 多 的 优 
化 设计 ， 它 的 实现 较为 复杂 。 在 7.7 节 中 ， 将 会 非常 详细 地 描述 它 的 实 
现 ， 当 然 ， 如 果 只 是 使 用 这 种 散 列 表 ， 并 不 需要 完全 看 异 7.7 市 ， 可 以 
只 看 一 下 7.7.3 节 的 例子 ， 这 将 会 简单 许多 。 不 过 ， 要 想 能 够 灵活 地 修改 
Nginx 的 各 种 使 用 散 列 表 的 代码 ， 还 是 建议 读者 仔细 阅读 一 下 7.7 节 的 内 


pd 


容 。 











7.2 ngx_queue_t 双 问 链 表 





ngx_queue_t 是 Nginx 提 供 的 一 个 基础 顺序 容器 ， 它 以 双 同 链表 的 方 
式 将 数据 组 织 在 一 起 。 在 Nginx 中 ，ngx_queue_t 数 据 结构 被 大 量 使 用 ， 
下 面 将 详细 介绍 它 的 特点 、 用 法 。 


7.2.1 为 什么 设计 ngx_queue_t 双 向 链表 


链表 作为 顺序 容 占 的 优势 在 于 ， 它 可 以 高 效 地 执行 搬入、 删除 、 合 
并 等 操作 ， 在 移动 链表 中 的 元 系 时 只 需要 修改 指针 的 指向 ， 因 此 ， 它 很 
适合 频繁 修改 容器 的 场合 。 在 Nginx 中 ， 链 表 是 必 不 可 少 的 ， 而 
ngx_queue_t 双 问 链 表 束 被 设计 用 于 达成 以 上 目的 。 





相对 于 Nginx 其 他 顺序 容器 ，ngx_queue_t 容 器 的 优势 在 于 : 
实现 了 排序 功能 。 


. 它 非常 轻 量 级 ， 是 一 个 纯粹 的 双向 链表 。 它 不 负责 链表 元 素 所 占 
内 存 的 分 配 ， 与 Nginx 封 装 的 ngx_pool t 内 存 池 完全 无 关 。 


“ 支持 两 个 链表 间 的 合并 。 


ngx_queue_t 容 器 的 实现 只 用 了 一 个 数据 结构 ngx_queue t， 它 仅 有 


两 个 成 员 prev、next， 如 下 所 示 : 


typedef struct ngx_queue s ngx_queue t; 
struct ngx_queue_s { 

ngx_queue_t *prev; 

ngx_queue t *next; 


}; 





因此 ， 对 于 链表 中 的 每 个 元 素来 说 ， 空 间 上 只 会 增加 两 个 指针 的 内 
存 消耗 。 


使 用 ngx_queue_t 时 可 能 会 遇 到 有 些 让 人 费解 的 情况 ， 因 为 链表 容器 
自 映 是 使 用 ngx_queue t 来 标识 的 ， 而 链表 中 的 每 个 元 素 同样 使 用 
ngx_queue_t 结 构 来 标识 自己 ， 并 以 ngx_queue_t 结 构 维持 其 与 相 邻 元 素 
的 关系 。 下 面 开 始 介绍 ngx_queue t 的 使 用 方法 。 





7.2.2” 双 同 链表 的 使 用 方法 


Nginx 在 设计 这 个 双 同 链表 时 ， 由 于 容器 与 元 素 共用 了 ngx_queue t 
结构 体 ， 为 了 避免 ngx_queue_t 结 构 体 成 员 的 意义 混乱 ，Nginx 封 装 了 链 
表 容 器 与 元 素 的 所 有 方法 ， 这 种 情况 非常 少见 ， 而 且 从 接 下 来 的 几 节 中 
可 以 看 到 ， 其 他 容器 都 需要 直接 使 用 成 员 变 量 来 访问 ， 唯 有 ngx_queue { 
双向 链表 只 能 使 用 图 7-1 中 列 出 的 方法 访问 容器 。 





3 BH 
ngx gueue t 容 需 


+ prev 
+next 


queue init() 
queue empty () 


ngx_queue_t 容 带 中 的 元 素 


queue insert head() Tprev 
queue insert tail() 
queue head () tngx gueue next () 
queue last () tnex queue prev () 
queue sentinel () Hngx gueue data () 
queue remove () tngx queue insert atfter () 
queue split () 
queue add() 

gx dueue middle () 

gxX gueue sort() 





图 7-1 ngx_queue_t 容 器 提供 的 操作 方法 


使 用 双 同 链表 容器 时 ， 需 要 用 一 个 ngx_queue_t 结 构 体 表示 容 右 本 
喘 ， 而 这 个 结构 体 共有 12 个 方法 可 供 使 用 ， 表 7-1 中 列 出 了 这 12 个 方法 
的 意义 。 


表 7-1 negx_queue_t 双 向 链表 容器 所 支持 的 方法 


方法 名 


ngx queue init(h) 


ngx_queue empty(h) 


ngx queue insert head(h, x) 


ngx queue insert tail(h, x) 


ngx_queue_ head(h) 


ngx queue last(h) 


ngx queue_ sentinel(h) 


ngx_queue remove(x) 


方法 名 


ngx_queue_split(h, q. n) 


ngx queue add(h. n) 


ngx queue middle(h) 


ngx queue sort(h,cmpfunc) 





参数 含义 执行 意义 

h 为 链表 容器 结构 体 ngx_queue_ t| 将 链表 容器 h 初 始 化 ， 这 时 会 自动 置 为 空 

的 指针 链表 
洽 测 链表 容器 中 是 否 为 空 ， 即 是 否 没 有 一 

h 为 链表 容器 结构 体 ngx 2 攻 
的 指 表 容 器 结 构 体 ngx_queue 上 | 个 元 素 存在 。 如 果 返 回 非 0， 表 示 链 表 了 是 

yiIBT 
空 的 


h 为 链表 容器 结构 体 ngx_queue_ 
t 的 指针 ,x 为 插入 元 素 结 构 体 中 | 将 元 素 x 插 入 到 链表 容器 的 头 部 
ngx_queue t 成员 的 指针 


h 为 链表 容 带 结构 体 ngx_queue_ 
t 的 指针 ,x 为 插入 元 素 结构 体 中 | 将 元 素 x 添加 到 链表 容器 4 的 末尾 
ngx_queue t 成员 的 指针 

h 为 链表 容器 结构 体 ngx_queue t| 返回 链表 容器 h 中 的 第 一 个 元 素 的 ngx_ 
的 指针 queue t 结 构 体 指针 

h 为 链表 容器 结构 体 ngx_ queue t| 返回 链表 容器 中 的 最 后 一 个 元 素 的 ngx_ 
的 指针 queue t 结构 体 指针 

h 为 链表 容 央 结构 体 ngx_queue { 
的 指针 

x 为 插入 元 素 结构 体 中 ngx_ 
queue_t 成 员 的 指针 


返回 链表 容器 结构 体 的 指针 


由 容器 中 移 除 x 元 素 


ngx_queue_split 用 于 拆 分 链表 , h 是 链表 
容器 ， 而 q 是 链表 4 中 的 一 个 元 素 。 这 个 方 

h 为 链表 容器 结构 体 ngx_queue t| 法 将 链表 h 以 元 素 q 为 界 拆 分 成 两 个 Er h 
的 指针 和 n， 其 中 由 原 链表 的 前 半 部 分 构成 ( 
括 q)， 而 n 由 原 链表 的 后 半 部 分 构 Ee. qd 是 
它 的 首 元 素 

h 为 链表 容器 结构 体 ngx_queue_ 
t 的 指针 ，a 为 另 一 个 链表 容器 结构 | 合并 链表 ， 将 n 链表 添加 到 bh 链表 的 末尾 
体 ngx_queue t 的 指针 
返回 链表 中 心 元 素 ， 如 ， 链 表 共 有 N 个 元 
hx 9 表 容 器 结构 体 ngx_queue t| 素 ,ngx_queue middle 方 法 将 返回 第 N/2+1 
个 元 素 。 例 如 ， 链 表 有 4 个 元 素 ， 将 会 返回 
第 3 个 元 素 (不 是 第 2 个 元 素 ) 

h 为 链表 容 需 结构 体 ngx_queue_| 使 用 插入 排序 法 对 链表 进行 排序 ，cmpfunc 
t 的 指针 ，cmpfunc 是 两 个 链表 元 素 | 需要 使 用 者 自己 实现 ， 它 的 原型 是 这 样 的 : 
的 比较 方法 ， 如 果 它 返回 正 数 ， 则 |ngx_int t (*cmpfunc)(const ngx_queue_t *， 
表示 以 升序 排序 const ngx_queue t *) 





对 于 链表 中 的 每 一 个 元 素 ， 其 类 型 可 以 是 任意 的 struct 结 构 体 ， 但 
这 个 结构 体 中 必须 要 有 一 个 ngx_queue_t 类 型 的 成 员 ， 在 向 链表 容器 中 添 
加 、 删 除 元 素 时 都 是 使 用 的 结构 体 中 ngx_queue_t 类 型 成 员 的 指针 。 当 
ngx_queue_t 作 为 链表 的 元 素 成 员 使 用 时 ， 它 具有 表 7-2 中 列 出 的 4 种 方 
0 











表 7-2 ngx_queue_t 双 向 链表 中 的 元 素 所 支持 的 方法 
有 RR 


q 为 链表 中 某 一 个 元 素 结构 体 的 ngx_ 
queue t 成 员 的 指针 

qd 为 链表 中 某 一 个 元 素 结构 体 的 ngx_ 
省 针 


ngx_queue next(q) 返回 q 元素 的 下 一 个 元 素 


ngx_ queue prev(q) 返回 gq 元素 的 上 一 个 元 素 


queue t 成 员 的 
q 为 链表 中 某 一 个 元 素 结构 体 的 ngx_ 
queue t 成 员 的 指针 ，type 为 链表 元 素 的 结 


返回 q 元 素 (ngx_ queue t 类 型 ) 
所 属 结构 体 (任何 struct 类 型 ， 其 
中 可 在 任意 位 置 包 含 ngx_queue ft 
类 型 的 成 员 ) 的 地 址 


ngx_queue_data(q. type, link) ”| 构 体 类 型 名 称 (该 结构 体 中 必须 包含 ngx_ 
queue t 类 型 的 成 员 )，link 是 上 面 这 个 结构 

体 中 ngx_queue t 类 型 的 成 员 名 字 
qd 为 链表 中 某 个 元 素 结 构 体 的 ngx_ 


ngx_queue insert_after(q. x) queue t 成 员 的 指针 ,x 为 插入 元 素 结构 体 | 将 元 素 x 插入 到 元 素 q 之 后 





中 ngx_queue t 成 员 的 指针 


在 表 7-1 和 表 7-2 中 ， 已 经 列 出 了 链表 文 持 的 所 有 方法 ， 下 面 将 以 一 
个 简单 的 例子 来 说 明 如 何 使 用 ngx_queue_t 双 癌 链 表 。 





7.2.3 ”使 用 双向 链表 排序 的 例子 





本 节 定 义 一 个 简单 的 链表 ， 并 使 用 ngx_queue_sort 方 法 对 所 有 元 素 


排序 。 在 这 个 例子 中 ， 可 以 看 到 如 何 定 义 、 初 始 化 ngx_queue_t 容 器 ， 如 
何 定 义 任 意 类 型 的 链表 元 素 ， 如 何 遍 历 链 表 ， 如 何 目 定义 排序 方法 并 执 


首先 ， 定 义 链表 元 素 的 结构 体 ， 如 下 面 的 TestNode 结 构 体 : 





typedef struct { 
u_char* str; 
ngx_queue_t dqEle; 
int num; 

} TestNode; 





链表 元 素 结构 体 中 必须 包含 ngx_queue_t 类 型 的 成 员 ， 当 然 它 可 以 在 
任意 的 位 置 上 。 本 例 中 它 的 上 面 有 一 个 char* 指 针 ， 下 面 有 一 个 整 型 成 
员 num， 这 样 是 允许 的 。 





排序 方法 需要 自 定义 。 下 面 以 TestNode 结 构 体 中 的 num 成 员 作为 排 
序 依 据 ， 实 现 compTestNode 方 法 作为 排序 过 程 中 任意 两 元 素 间 的 比较 方 
人 








ngx_int_t compTestNode(const ngx_queue t* a, ， const ngx_dueue_t* pb) 


/* 首 先 使 用 


ngx_queue_data 方 法 由 


ngx_queue_t 交 量 获取 元 素 结构 体 


TestNode 的 地 址 


*/ 
TestNode* aNode 
TestNode* bNode 
// 返回 


ngx_queue_data(a, TestNode, dqEle); 
ngx_queue_data(b, TestNode, dqEle); 


num 成 员 的 比较 结果 


return aNode->num > bNode->num; 


} 





这 个 比较 方法 结合 ngx_queue_sort 方 法 可 以 把 链表 中 的 元 系 按 照 hum 
的 大 小 以 升序 排列 。 在 此 例 中 ， 可 以 看 到 ngx_queue_data 的 用 法 ， 即 可 
以 根据 链表 元 素 结 构 体 TestNode 中 的 qEle 成 员 地 址 换算 出 TestNode 结 构 
体 变 量 的 地 址 ， 这 是 面向 过 程 的 C 语 言 编写 的 ngx_queue {链表 之 所 以 能 
够 通用 化 的 关键 。 下 面 来 看 一 下 ngx_queue_data 的 定义 : 





#define ngx_queue_data(q,type,link) \ 
(type *) ((u_char *) q - offsetof(type, link)) 





在 4.2.2 市 中 曾经 提 到 过 offsetof 函 数 是 如 何 实现 的 ， 即 它 会 返回 link 
成 员 在 type 结 构 体 中 的 偏 移 量 。 例 如 ， 在 上 例 中 ， 可 以 通过 ngx_queue { 
类 型 的 指针 减 去 qEle 相 对 于 TestrNode 的 地 址 偏 移 量 ， 得 到 TestrNode 结 构 
体 的 地 址 。 











下 面 开 始 定义 双 辐 链表 容器 queueContainer， 并 将 其 初始 化 为 空 链 
表 ， 如 下 所 示 。 








ngx_queue_t queueContainer; 
ngx_queue_init(&queueContainer); 











链表 容器 以 ngx_gqueue_t 定 义 即 可 。 注 意 ， 对 于 表示 链表 容器 的 
ngx_queue_t 结 构 体 ， 必 须 调用 ngx_queue_init 进 行 初 始 化 。 








ngx_queue _t 双 问 链 表 是 完全 不 负责 分 配 内 存 的 ， 每 一 个 链表 元 素 必 
须 自 己 管理 自己 所 占用 的 内 存 。 因 此 ， 本 例 在 进程 栈 中 定义 了 5 个 
TestNode 结 构 体 作为 链表 元 素 ， 并 把 它们 的 num 成 员 初始 化 为 0、1、2、 
3、4， 如 下 所 示 。 








int i = 0; 
TestNode node[S5]; 
for (; i < 5; i++) 


node[il].num = 工 ; 





下 面 把 这 5 个 TestrNode 结 构 体 添加 到 queueContainer 链 表 中 ， 注 意 ， 
这 里 同时 使 用 了 ngx_queue_insert_tail、ngx_queue_insert_head、 
ngx_queue_insert_after 3 个 添加 方法 ， 读 者 不 妨 思考 一 下 链表 中 元 素 的 顺 
序 是 什么 样 的 。 








ngx_queue_insert_tail(&queueContainer, &node[0].qgEle); 
ngx_queue_insert_head(&queueContainer, &node[1].qgEle); 
ngx_queue_insert_tail(&queueContainer, &node[2].qgEle); 
ngx_queue_insert_after(&queueContainer, &node[3].qgEle); 
ngx_queue_insert_tail(&queueContainer, &node[4].qgEle); 




















根据 表 7-1 中 介绍 的 方法 可 以 得 出 ， 如 果 此 时 的 链表 元 素 顺序 以 num 
成 员 标识 ， 那 么 应 该 是 这 样 的 : 3、1、0、2、4。 如 果 有 疑问 ， 不 妨 写 
个 过 历 链表 的 程序 检验 一 下 顺序 是 否 如 此 。 下 面 就 根据 表 7-1 中 的 方法 
说 明 编写 一 段 简 单 的 过 历 链表 的 程序 。 











ngx_queue_t* q; 
for (q = ngx_queue _ head(&queueContainer); 
q != ngx_queue_sentinel(&queueContainer ) ， 


q = ngx_queue_next(q)) 


‘ 
TestNode* eleNode = ngx_queue data(q, TestNode, qEle); 


// 处 理 当前 的 链表 元 素 


eleNode 





上 面 这 段 程序 将 会 依次 从 链表 头 部 过 历 到 尾部 。 反 回 壳 历 也 很 徐 
单 。 读 者 可 以 尝试 使 用 ngx_queue_last 和 ngx_gueue_prev 方 法 编写 相关 代 
码 。 


下 面 开始 执行 排序 ， 代 码 如 下 所 示 。 





ngx_queue_sort(&queueContainer, compTestNode); 





这 样 ， 链 表 中 的 元 素 就 会 以 0、1、2、3、4 (Cnum 成 员 的 值 ) 的 升 
序 排列 了 。 





表 7-1 中 列 出 的 其 他 方法 就 不 在 这 里 一 一 举例 了 ， 使 用 方法 非常 相 
似 。 


7.2.4” 双 同 链表 是 如 何 实现 的 


本 节 将 说 明 ngx_gqueue_t 链 表 容 右 以 及 元 素 中 prev 成 员 、next 成 员 的 
意义 ， 整 个 链表 就 是 通过 这 两 个 指针 成 员 实 现 的 。 





下 面 先 来 看 一 下 ngx_queue_t 结 构 体 作为 容器 时 其 prev 成 员 、next 成 
员 的 意义 。 当 容器 为 空 时 ，prev 和 next 都 将 指向 容器 本 身 ， 如 图 7-2 所 


让 
pt 
O 


如 图 7-2 所 示 ， 如 果 在 某 个 结构 体 中 定义 了 ngx_queue t 容 器 ， 其 


prev 指 针 和 next 指 针 都 会 指 癌 ngx_queue_t 成 员 的 地 址 。 





DH .2 
他 Tr RE Es HY 


图 7-2” 空 容器 时 ngx_queue_t 结 构 体 成 员 的 值 


当 容 右 不 为 空 时 ，ngx_queue_t 容 器 的 next 指 针 会 指 疝 链表 的 第 1 个 
元 素 ， 而 prev 指 针 会 指 癌 链表 的 最 后 1 个 元 素 。 如 图 7-3 所 示 ， 这 时 链表 
中 只 有 1 个 链表 元 隶 ， 容 器 的 next 指 针 和 prev 指 针 都 将 指 癌 这 个 唯一 的 链 








表 元 素 。 





nox_duUeue tf 





noX_dueue 1 


ngx_queue_1t 容 融 容器 只 有 1 个 元 素 


图 7-3 ” 当 仅 含 1 个 元 素 时 ， 容 器 、 元 素 中 的 ngx_queue_t 结 构 体 成 员 的 值 


对 于 每 个 链表 元 素来 说 ， 其 prev 成 员 都 指向 前 一 个 元 素 〔 不 存在 时 
指 问 链 表 容 姻 〉， 而 next 成 员 则 指向 下 一 个 元 素 不 存在 时 指 癌 链表 容 
器 ) ， 这 在 图 7-3 中 可 以 看 到 。 


当 容 器 中 有 两 个 元 素 时 ，prev 和 next 的 指向 如 图 7-4 所 示 。 

















ngx_queue_t 容 还 容 夭 中 的 第 1 个 元 素 容器 中 的 第 2 个 元 素 
图 7-4 ” 当 含 有 两 个 或 多 个 元 素 时 ， 容 器 、 元 素 中 的 ngx_queue_t 结 构 体 
中 prev、next 成 员 的 值 


图 7-4 很 好 地 诠释 了 前 面 的 定义 ， 容 器 中 的 prev 成 员 指 加 最 后 1 个 也 








束 是 第 2 个 元 素 ，next 成 员 指 同 第 1 个 元 素 。 第 1 个 元 素 的 prev 成 员 指 问 容 
嚣 本身， 而 其 next 成 员 指 向 第 2 个 元 素 。 第 2 个 元 素 的 prev 成 员 指 向 第 1 个 
元 素 ， 其 next 成 员 则 指向 容器 本 和 续 。 





ngx_queue_t 的 实现 就 是 这 么 人 简单， 但 它 的 排序 算法 ngx_queue_sort 
使 用 的 插入 排序 ， 并 不 适合 为 庞大 的 数据 排序 。 


7.3 ngx_array_t 动 态 数组 


ngx_array_t 是 一 个 顺序 容 占 ， 它 在 Nginx 中 大 量 使 用 。ngx_array_t 容 
器 以 数组 的 形式 存储 元 素 ， 并 文 持 在 达到 数组 容量 的 上 限时 动态 改变 数 
组 的 大 小 。 


7.3.1 为 什么 设计 ngx_array_t 动 态 数组 


数组 的 优势 是 它 的 访问 速度 。 由 于 它 使 用 一 块 完整 的 内 存 ， 并 按照 
固定 大 小 存储 每 一 个 元 系 ， 所 以 在 访问 数组 的 任意 一 个 元 素 时 ， 都 可 以 
根据 下 标 直 接 寻 址 找到 它 ， 男 外 ， 数 组 的 访问 速度 是 常量 级 的 ， 在 所 有 
的 数据 结构 中 它 的 速度 都 是 最 快 的 。 然 而 ， 正 是 由 于 数组 使 用 一 块 连续 
的 内 存 存储 所 有 的 元 素 ， 所 以 它 的 大 小 直接 决定 了 所 消耗 的 内 存 。 
见 ， 如 果 预 分 配 的 数组 过 大 ， 肯 定 会 浪费 宝贵 的 内 存 资 源 。 那 么 ， 数 组 
的 大 小 完 竟 应 该 分 配 多 少 才 是 够 用 的 呢 ? 当 数 组 大 小 无 法 确定 时 ， 动 态 
数组 就 “登场 ”了 。 

















本 





C++ 语 言 的 STL 中 的 vector 容 器 束 像 ngx_array_t 一 样 是 一 个 动态 数 
组 。 它 们 在 数组 的 大 小 达到 已 经 分 配 内 存 的 上 限时 ， 会 自动 扩充 数组 的 
大 小 。 具 备 了 这 个 特点 之 后 ，ngx_array_t 动 态 数 组 的 用 处 就 大 多 了 ， 而 
且 它 内 置 了 Nginx 封 朔 的 内 存 池 ， 因 此 ， 它 分 配 的 内 存 也 是 在 内 存 池 中 








申请 得 到 。ngx_array_t 容 器 具备 以 下 3 个 优点 : 
` 访问 速度 快 。 
" 允许 元 素 个 数 具 备 不 确定 性 。 
- 负责 元 素 占 用 内 存 的 分 配 ， 这 些 内 存 将 由 内 存 池 统一 管理 。 


7.3.2 动态 数组 的 使 用 方法 


ngx_array_t 动 态 数 组 的 实现 仅 使 用 1 个 结构 体 ， 如 下 所 示 。 








typedef struct ngx_array_s ngx_array_t; 
struct ngx_array_s { 
// elts 指 向 数组 的 首 地 址 


void *elts; 
// nelts 是 数组 中 己 经 使 用 的 元 素 个 数 


ngx_uint_t nelts,; 
// 每 个 数组 元 素 占用 的 内 存 大 小 


size_t size,; 
// 当前 数组 中 能 够 容纳 元 素 个 数 的 总 大 小 


ngx_uint_t nalloc; 
// 内 存 池 对 象 


ngx_pool t *pool; 
}; 


ee | 





在 上 面 这 上段 代码 中 己 经 简单 描述 了 ngx_array_t 结 构 体 中 各 成 员 的 意 
义 ， 通 过 图 7-5， 读 者 可 以 有 更 直观 的 理解 。 


共 分 配 了 nalloc 个 元 素 









f 


已 经 存储 了 nelts 个 元 素 


-个 元 素 所 占 字 (size ) 






+elts 
elts 指 问 动态 数组 的 首 地 址 +nelts 

+ siZe 
+nalloc 
+pool 


array create () 


array init () 
array destroy () 
afrray push() 
array push n() 


图 7-5 ngx_array_t 动 态 数组 结构 体 中 的 成 员 及 其 提供 的 方法 





从 图 7-5 中 可 以 看 出 ，ngx_array_t 动 态 数组 还 提供 了 5 个 基本 方法 ， 


它们 的 意义 见 表 7-3 


表 7-3 ngx_atray_t 动 态 数 组 提供 的 方法 
方法 名 执行 意义 


ry a S| 机 eg 创建 1 个 动态 数组 ， 并 预 分 配 n 个 大 小 
元 素 的 最 大 个 数 ，size 是 每 一 为 size 的 内 存 空间 
“元素 所 占用 的 内 存 大 小 
个 动态 数组 结构 体 的 
译 内 存 池 , n 是 初始 | 初始 化 1 个 已 经 存在 的 动态 数组 ， 并 预 


ngx array_create(ngx pool t *p, 


ngx uint tn, size t size) 


ngx_ array_init(ngx_ array_t *a, 





p} 
ngx pool t *p. ngx uint tn, size tsize) | 分 丁 元 素 的 的 最 大 个 数 ，size 是 | 分 配 n 个 大 小 为 size 的 内 存 空间 
“元 素 所 占用 的 内 存 大 小 





销毁 已 经 分 配 的 数组 元 素 空 间 和 ngx_ 
array t 动 态 数 组 对 象 。 注 意 : ngx array_ 


个 动态 数组 结构 体 的 
a destroy 最 好 与 ngx_array_create 配对 使 用 ， 


ngx array_destroy(ngx array_t *a) 
因为 ngx_array destroy 同 时 会 回收 ngx_ 


array_t 结构 体 自身 占用 的 内 存 


( 续 ) 
方法 名 i 
问 当 前 a 动态 数组 中 添加 1 个 元 素 ， 返 


回 的 是 这 个 新 添加 元 素 的 地 址 注意 : 如 
果 动 态 数组 已 经 达到 容量 上 限 ， 这 时 会 自 
动 扩容 ， 到 底 扩容 多 少 字 节 ， 在 7.3.4 节 中 
说 明 


ngx array_push(ngx array_t *a) 








ngx array_push n(ngx array_t *a. -动态 数组 结构 体 的 指 癌 当 前 a 动态 数组 中 添加 n 个 元 素 ， 返回 
ngx_ uint tn) 有 :需要 添加 元 素 的 个 数 “| 的 是 新 添加 这 批 元 素 中 第 一 个 元 素 的 地 址 


如 果 使 用 已 经 定义 过 的 ngx_array_t 结 构 体 ， 那 么 可 以 先 调用 
ngx_array_init 方 法 初始 化 动态 数组 。 如 果 要 重新 在 内 存 池 上 定义 
ngx_array_t 结 构 体 ， 则 可 以 调用 ngx_array_create 方 法 创建 动态 数组 。 
两 个 方法 都 会 预 分 配 一 定 容量 的 数组 元 素 。 


YY 


在 问 动态 数组 中 添加 新 元 素 时 ， 最 好 调用 ngx_array_push 或 者 
ngx_array_push_n 方 法 ， 这 两 个 方法 会 在 达到 数组 预 分 配 容 量 上 限时 自 








动 扩容 ， 这 比 直 接 操 作 ngx_array_t 结 构 体 中 的 成 员 要 好 得 多 ， 有 具体 将 在 
7.3.3 贡 的 例子 中 详细 说 明 。 


@ 注意 “因为 nge_array_destroy 是 在 内 存 池 中 销毁 动态 数组 及 其 分 
配 的 元 素 内 存 的 (如果 动态 数组 的 nex_attay_t 结 构 体 内 存 是 利用 栈 等 非 
内 存 池 方 式 分 配 ， 那 么 调用 ngx_array_destroy 会 导致 不 可 预 估 的 错误 ) ， 
所 以 它 必 须 与 ngx_attay_cfeate 配 对 使 用 。 


7.3.3 ”使 用 动态 数组 的 例子 


本 节 以 一 个 简 蛙 的 例子 说 明 如 何 使 用 动态 数组 。 这 里 仍然 以 7.2.3 中 
介绍 的 TestNode 作 为 数组 中 的 元 素 类 型 。 首 先 ， 调 用 ngx_array_create 方 
法 创建 动态 数组 ， 代 码 如 下 。 





ngx_array_t* dynamicArray = ngx_array_create(cf->pool, 1, sizeof(TestNode)); 











这 里 创建 的 动态 数组 只 预 分 配 了 1 个 元 素 的 空间 ， 每 个 元 素 占 用 的 
内 存 字 节 数 为 sizeof(TestNode)， 也 就 是 TestNode 结 构 体 占 用 的 空间 大 


小 。 


然后 ， 调 用 ngx_array_push 方 法 回 dynamicArray 数 组 中 添加 两 个 元 
素 ， 代 码 如 下 。 





TestNode* a = ngx_array_push(dynamicArray ) ; 
a->num = 工 ; 


a = ngx_ array_push(dynamicArray ) 
a->num = 2; 





这 两 个 元 素 的 num 值 分 别 为 1 和 2。 注 意 ， 在 添加 第 2 个 元 素 时 ， 实 
际 已 经 发 生 过 一 次 扩容 了 ， 因 为 调用 ngx_array_create 方 法 时 只 预 分 配 了 
1 个 元 素 的 空间 。 下 面 尝 试用 ngx_array_push_n 方 法 一 次 性 添加 3 个 元 
素 ， 代 码 如 下 。 








TestNode* b = ngx_array_push_n(dynamicArray, 3); 
b->num = 3; 
(b+1)->num 
(b+2)->num 


4; 
5; 


1 1 





这 3 个 元 素 的 num 值 分 别 为 3、4、5。 下 面 来 看 一 下 是 如 何人 遍历 
dynamicArray 动 态 数组 的 ， 代 码 如 下 。 





TestNode* nodeArray = dynamicArray->elts; 
ngx_uint_t arraySeq = 0; 
for (; arraySeq < dynamicArray->nelts; arraySeq++) 


{ 
a = nodeArray + arraySeq; 
// 下 面 处 理 数 组 中 的 元 素 

a 

} 





了 解 了 遍历 dynamicArray 动 态 数 组 的 方法 后 ， 再 来 看 一 下 销毁 动态 
数组 的 方法 ， 这 天 非常 简单 了 ， 如 下 所 示 : 





ngx_array_destroy(dynamicArray); 





7.3.4 动态 数组 的 扩容 方式 











本 市 将 介绍 当 动 态 数组 达到 容量 上 限时 是 如 何 进行 扩容 的 。 
ngx_array_push 和 ngx_array_push_n 方 法 都 可 能 引发 扩容 操作 。 


当 已 经 使 用 的 元 素 个 数 达 到 动态 数组 预 分 配 元 系 的 个 数 时 ， 再 次 调 
用 ngx_array_push 或 者 ngx_array_push_n 方 法 将 引发 扩容 操作 。 
ngx_array_push 方 法 会 申请 ngx_array_t 结 构 体 中 size 字 节 大 小 的 内 存 ， 而 
ngx_array_push_n 方 法 将 会 申请 n(n 是 ngx_array_push_n 的 参数 ， 表 示 需 
要 添加 n 个 元 素 ) 个 size 字 节 大 小 的 内 存 。 每 次 扩容 的 大 小 将 受制 于 内 存 
池 的 以 下 两 种 情形 : 





. 如 果 当 前 内 存 池 中 剩余 的 空间 大 于 或 者 等 于 本 次 需要 新 增 的 空 
间 ， 那 么 本 次 扩容 将 只 扩充 新 增 的 空间 。 例 如 ， 对 于 ngx_atray_push 方 法 
来 说 ， 就 是 扩充 1 个 元 素 ， 而 对 于 ngx_array_push_n 方 法 来 说 ， 就 是 扩充 n 


个 元 素 。 


` 如 果 当 前 内 存 池 中 剩余 的 空间 小 于 本 次 需要 新 增 的 空间 ， 那 么 对 
ngx_array_push 方 法 来 说 ， 会 将 原先 动态 数组 的 容量 扩容 一 倍 ， 而 对 于 
ngx_atray_push_n 来 说 ， 情 况 更 复杂 一 些 ， 如 果 参 数 n 小 于 原先 动态 数组 
的 容量 ， 将 会 扩容 一 倍 ; 如 果 参 数 n 大 于 原先 动态 数组 的 容量 ， 这 时 会 
分 配 2Xn 大 小 的 空间 ， 扩 容 会 超过 一 倍 。 这 体现 了 Nginx 预 估 用 户 行为 


的 设 计 忆 想 心 





在 以 上 两 种 情形 下 扩容 的 字 节 数 都 与 每 个 元 素 的 大 小 相关 。 


@@ 注意 上述 第 2 种 情形 涉及 数据 的 复制 。 新 扩容 一 售 以 上 的 动态 
数组 将 在 全 新 的 内 存 块 上 ， 这 时 将 有 一 个 步骤 将 原 动 态 数组 中 的 元 素 复 
制 到 新 的 动态 数组 中 ， 当 数组 非常 大 时 ， 这 个 步 又 可 能 会 耗 时 较 长 。 





7.4 ngx_jlist_t 单 向 链表 


ngx_list_t 也 是 一 个 顺序 容器 ， 它 实际 上 相当 于 7.3 节 中 介绍 的 动态 
数组 与 单 向 链表 的 结合 体 ， 只 是 扩容 起 来 比 动态 数组 简单 得 多 ， 它 可 以 
一 次 性 扩容 1 个 数组 。 在 图 3-2 中 描述 了 ngx_list_t 容 器 中 各 成 员 的 意义 ， 
而 且 在 3.2.3 节 中 详细 介绍 过 它 的 用 法 ， 这 里 不 再 袭 述 。 








7.5 ngx_rbtree_t 红 黑 树 


ngx_rbtree_t 是 使 用 红 黑 树 实现 的 一 种 关联 容器 ，Nginx 的 核心 模块 
《如 定时 器 管理 、 文 件 缓存 模块 等 ) 在 需要 快速 检索 、 查 找 的 场合 下 都 
使 用 了 ngx_rbtree_t 容 器 ， 本 节 将 系统 地 讨论 ngx_rbtree_t 的 用 法 ， 并 以 
一 个 贯穿 本 节 始 终 的 例子 对 它 进行 说 明 。 在 这 个 例子 中 ， 将 有 10 个 元 素 
需要 存储 到 红 黑 树 窗口 中 ， 每 个 元 素 的 关键 字 是 简单 的 整 型 ， 分 别 为 
1、6、8、11、13、15、17、22、25、27， 以 下 的 例子 中 都 会 使 用 到 这 
10 个 节点 数据 。 





7.5.1 为 什么 设计 ngx_rbtree_t 红 黑 树 


绍 的 容 需 都 是 顺序 容器 ， 它 们 的 检索 效率 通 单 情况 下 都 比较 
兰 ， 一 般 只 能 过 有 历 检索 指定 元 系 。 当 需要 容 髓 的 检索 速度 很 快 ， 或 者 需 
要 文 持 范围 得 询 时 ，ngx_rbtree_t 红 黑 树 容器 是 一 个 非常 好 的 选择 。 








红 黑 树 实际 上 是 一 种 上 自 平 衡 二 又 碍 找 树 ， 但 什么 是 二 又 树 昵 ? 二 又 
树 是 每 个 节 扣 最 多 有 两 个 子 树 的 树 结构 ， 每 个 市 点 都 可 以 用 于 存储 数 
据 ， 可 以 由 任 1 个 节点 访问 它 的 左右 子 树 或 者 父 市 皮 。 








那么 ， 什 么 是 二 又 碍 找 树 呢 ? 二 又 查找 树 或 者 是 一 柠 空 树 ， 或 者 是 
具有 下 列 性 质 的 二 又 树 。 


. 每 个 节点 都 有 一 个 作为 查找 依据 的 关键 码 (key) ， 所 有 节点 的 
关键 码 互 不 相同 。 


“ 左 子 树 〈 如 果 存 在 ) 上 所 有 节点 的 关键 码 都 小 于 根 节 点 的 关键 
码 。 


` 右 子 树 (如 果 存 在 ) 上 所 有 节点 的 关键 码 都 大 于 根 节点 的 关键 
码 。 


` 左 子 树 和 右 子 树 也 是 二 又 查找 树 。 














这 样 ， 一 棵 二 又 碍 找 树 的 所 有 元 素 节点 都 是 有 序 的 。 在 二 又 树 的 形 
态 比 较 平衡 的 情况 下 ， 它 的 检索 效率 很 高 ， 有 点 类 似 于 二 分 法 检索 有 序 
数组 的 效率 。 一 般 情况 下 ， 查 询 复 杂 度 是 与 目标 节点 到 根 节点 的 距离 
( 即 深度 ) 有 关 的 。 然 而 ， 不 断 地 添加 、 删 除 节点 ， 可 能 造成 二 又 查找 
树 形态 非常 不 平衡 ， 在 极端 情形 下 它 会 变 成 单 链表 ， 检 索 效 率 也 就 会 变 
得 低下 。 例 如 ， 在 本 节 的 例子 中 ， 依 次 将 这 10 个 数据 1、6、8、11、 
13、15、17、22、25、27 添 加 到 一 棵 普通 的 空 二 又 得 找 树 中 ， 它 的 形态 
如 图 7-6 所 示 。 























第 1 个 元 际 1 添 加 到 空 二 又 树 后 目 动 成 为 根 节 点 ， 而 后 陆续 添加 的 元 
素 正 好 以 升序 递增 ， 最 终 的 形态 必然 如 图 7-6 所 示 ， 也 就 是 相当 于 单 链 
表 了 ， 由 于 树 的 深度 太 大 ， 因 此 各 种 操作 的 效率 都 会 很 低下 。 





图 7-6 ”普通 的 二 又 查找 树 可 能 非常 不 平衡 


什么 是 自 平衡 二 叉 查 找 树 ? 在 不 断 地 向 二 又 查找 树 中 添加 、 删 除 节 
点 时 ， 二 又 查找 树 自身 通过 形态 的 变换 ， 始 终 保 持 着 一 定 程度 上 的 平 
衡 ， 即 为 自 平衡 二 又 查找 树 。 自 平衡 二 又 查找 树 只 是 一 个 概念 ， 它 有 许 
多 种 不 同 的 实现 方式 ， 如 AVL 树 和 红 黑 树 。 红 黑 树 是 一 种 自 平衡 性 较 好 











的 二 又 查找 树 ， 它 在 Linux 内 核 、C++ 的 STL 库 等 许多 场合 下 都 作为 核心 
数据 结构 使 用 。 本 节 讲 述 的 ngx_rbtree_t 容 器 就 是 一 种 由 红 黑 树 实现 的 自 
平衡 二 叉 查 找 树 。 


ngx_rbtree_t 红 黑 树 容器 中 的 元 系 都 是 有 序 的 ， 它 文 持 快 速 的 检索 、 
插入 、 删 除 操 作 ， 也 支持 范围 查询 、 避 历 等 操作 ， 是 一 种 应 用 场景 非常 
广泛 的 高 级 数据 结构 。 


7.5.2” 红 黑 树 的 特性 
本 节 讲 述 红 黑 树 的 特性 ， 对 于 只 想 了 解 如 何 使 用 ngx_rbtree_t 容 妖 的 
读者 ， 可 以 跳 过 本 节 。 


红 黑 树 是 指 每 个 节点 都 带 有 颜色 属性 的 二 又 查找 树 ， 其 中 颜色 为 红 
色 或 黑色 。 除 了 二 又 碍 找 树 的 一 般 要 求 以 外 ， 对 于 红 黑 树 还 有 如 下 的 额 
外 的 特性 。 


特性 1: 节点 是 红色 或 黑色 。 
特性 2: 根 节 点 是 黑色 。 
特性 3: 所 有 叶子 节点 都 是 黑色 〈 时 子 是 NI 节点， 也 叫 “ 哨 兵 ”) 。 


特性 4， 每 个 红色 节点 的 两 个 子 节点 都 是 黑色 《每 个 叶子 节点 到 根 


节点 的 所 有 路 径 上 不 能 有 两 个 连续 的 红色 节点 ) 。 


特性 5: 从 任 一 节点 到 其 每 个 叶子 节点 的 所 有 简单 路 径 都 包含 相同 
数目 的 黑色 节点 。 





这 些 约束 加 强 了 红 黑 树 的 关键 性 质 : 从 根 节点 到 叶子 节点 的 最 长 可 
能 路 径 长 度 不 大 于 最 短 可 能 路 径 的 两 倍 ， 这 样 这 个 树 大 致 上 就 是 平衡 的 
了 。 因 为 二 又 树 的 操作 《比如 插入 、 删 除 和 查找 某 个 值 的 最 慢 时 间 ) 都 
是 与 树 的 高 度 成 比例 的 ， 以 上 的 5 个 特性 保证 了 树 的 高 度 〈 最 长 路 
径 ) ， 所 以 它 完全 不 同 于 普通 的 二 又 查找 树 。 





这 些 特 性 为 什么 可 以 导致 上 述 结 果 呢 ? 因为 特性 4 实际 上 决定 了 1 个 
路 径 不 能 有 两 个 毗连 的 红色 节点 ， 这 一 点 就 足够 了 。 最 短 的 可 能 路 径 都 
是 黑色 节点 ， 最 长 的 可 能 路 径 有 交替 的 红色 节点 和 黑色 节点 。 根 据 特性 
5 可 知 ， 所 有 最 长 的 路 径 都 有 相同 数目 的 黑色 节点 ， 这 就 表明 了 没有 路 
径 能 大 于 其 他 路 径 长 度 的 两 倍 。 








在 本 节 的 例子 中 ， 仍 然 按照 顺序 将 这 10 个 升序 递增 的 元 又 添加 到 至 
的 ngx_rbtree_t 红 黑 树 容器 中 ， 此 时 ， 我 们 会 发 现 根 节点 不 是 第 1 个 添加 
的 元 素 1， 而 是 元 素 11。 实 际 上 ， 依 次 添加 元 素 1、6、8、11、13、15、 
17、22、25、27 后 ， 红 黑 树 的 形态 如 图 7-7 所 示 。 





+root 

+sentinel 

tinsert 

ngx rbtree init () 
+ngx rbtree insert () 
+ngx rbtree delete () 

















左右 子 树 





左右 子 树 


左右 子 树 


图 7-7 ngx_tbtree_t 红 黑 树 的 典型 图 示 (其 中 无 底 纹 节点 表示 红色 ， 有 


底 纹 节点 表示 黑色 ) 


如 图 7-7 所 示 的 是 一 柠 相 对 平衡 的 树 ， 它 满足 红 黑 树 的 5 个 特性 ， 最 
长 路 径 长 度 不 大 于 最 短路 径 的 2 倍 。 在 ngx_rbtree_t 红 黑 树 在 发 现 自身 满 
足 不 了 上 述 5 个 红 黑 树 特性 时 ， 将 会 通过 旋转 《加 左旋 转 或 者 回 右 旋 





转 ) 子 树 来 使 树 达到 平衡 。 这 里 不 再 讲述 红 黑 树 的 旋转 功能 ， 实 际 上 它 
非常 简单 ， 读 者 可 以 通过 ngx_rbtree_left_rotate 和 ngx_rbtree_right_rotate 
方法 来 了 解 旋转 功能 的 实现 。 


7.5.3” 红 黑 树 的 使 用 方法 


红 黑 树 容 器 由 ngx_rbtree_t 结 构 体 承 描 ，ngx_rbtree_t 的 成 员 和 它 相 
关 的 方法 在 图 7-7 中 可 以 看 到 ， 下 面 进行 详细 介绍 。 首 先 ， 需 要 了 解 一 
下 红 黑 树 的 节点 结构 ， 如 图 7-8 所 示 。 


+ key 

+ left 

+ right 

+ parent 

+ color 

+ data 

Fngx rbt red() 

Hnex rbt black() 
gx rbt 1s red() 
gx rbt 1s black() 


gx rbt copy color() 


gx rbtree sentinel init() 


rbtree min() 





图 7-8 红 黑 树 节 点 的 结构 体 及 其 提供 的 方法 


ngx_rbtree_node_t 结 构 体 用 来 表示 红 黑 树 中 的 一 个 节点 ， 它 还 提供 
了 7 个 方法 用 来 操作 节点 。 下 面 了 解 一 下 ngx_rbtree_node _t 结 构 体 的 定 
义 ， 代 码 如 下 。 





typedef ngx_uint t ngx_rbtree key_t; 
typedef struct ngx_rbtree node s ngx_rbtree node t; 
struct ngx_rbtree node s { 

// 无 符号 整 型 的 关键 字 








ngx_rbtree_ key_t key; 
/1 直子 节点 

ngx_rbtree_node 上 *]eft 
// 右 子 节点 

ngx_rbtree_node 上 *right， 
// 父 节点 

ngx_rbtree_node 上 *parent ; 


// 节点 的 颜色 ， 


u_char color; 
// 仅 


1 个 字 节 的 节点 数据 。 由 于 表示 的 空间 太 小 ， 所 以 一 般 很 少 使 用 


u_char data; 


ngx_rbtree_node_t 是 红 黑 树 实 现 中 必须 用 到 的 数据 结构 ， 一 般 我 们 
把 它 放 到 结构 体 中 的 第 1 个 成 员 中 ， 这 样 方便 把 目 定 义 的 结构 体 强 制 转 
换 成 ngx_rbtree_node_t 类 型 。 例 如 : 








typedef struct { 
/* 一 般 都 将 


ngx_rbtree_node_t 节 点 结构 体 放 在 自 定义 数据 类 型 的 第 


1 位 ， 以 方便 类 型 的 强制 转换 


*/ 
ngx_rbtree_node_t node,; 
ngx_uint_t num; 

} TestRBTreeNode ; 





如 果 这 里 希望 容器 中 元 素 的 数据 类 型 是 TestRBTreeNode， 那 么 只 需 
要 在 第 1 个 成 员 中 放 上 ngx_rbtree_node_t 类 型 的 node 即 可 。 在 调用 图 7-7 
中 ngx_rbtree_t 容 器 所 提供 的 方法 时 ， 需 要 的 参数 都 是 ngx_rbtree_node_t 
类 型 ， 这 时 将 TestRBTreeNode 类 型 的 指针 强制 转换 成 ngx_rbtree_node t 
即 可 。 


ngx_rbtree_node_t 结 构 体 中 的 key 成 员 是 每 个 红 黑 树 节 点 的 关键 字 ， 
它 必 须 是 整 型 。 红 黑 树 的 排序 主要 依据 key 成 员 〈( 当然， 目 定 义 
ngx_rbtree_insert_pt 方 法 后 ， 市 点 的 其 他 成 员 也 可 以 在 key 排 序 的 基础 上 
影响 红 黑 树 的 形态 )。 在 图 7-7 所 示例 子 中 ，1、6、8、11、13、15、 


17、22、25、27 这 些 数字 都 是 每 个 节点 的 key 关 键 字 。 


下 面 看 一 下 表示 红 黑 树 的 ngx_rbtree_t 结 构 体 是 如 何 定义 的 ， 代 码 如 
下 





typedef struct ngx_rbtree s ngx_rbtree _t， 
/* 为 解决 不 同 节点 含有 相同 关键 字 的 元 素 冲 突 问题 ， 红 黑 树 设置 了 





ngx_rbtree_insert_pt 指 针 ， 这 样 可 灵活 地 添加 冲突 元 素 





*/ 
typedef void (*ngx_rbtree insert pt) (ngx_rbtree node t *root, 
ngx_rbtree node t *node, ngx_rbtree node t *sentinel); 
struct ngx_rbtree s { 
// 指向 树 的 根 节 点 。 注 意 ， 根 节点 也 是 数据 元 素 





ngx_rbtree_node 上 *root 
// 指向 


NIL 哨 兵 节点 


ngx_rbtree_node 上 *sentinel; 
// 表示 红 黑 树 添加 元 素 的 函数 指针 ， 它 决定 在 添加 新 节点 时 的 行为 究竟 是 替换 还 是 新 增 





ngx_rbtree_insert_pt insert; 


}; 








在 上 段 代码 中 ，ngx_rbtree_t 结 构 体 的 root 成 员 指 回 根 节点 ， 而 
sentinel 成 员 指 同 哨 兵 市 态 ， 这 很 清晰 。 然 而 ，insert 成 员 作为 一 个 


ngx_rbtree_insert_pt 类 型 的 函数 指针 ， 它 的 意义 在 哪里 呢 ? 








红 黑 树 是 一 个 通用 的 数据 结构 ， 它 的 节点 《或 者 称 为 容 露 的 元 素 ) 
可 以 是 包含 基本 红 黑 树 节点 的 任意 结构 体 。 对 于 不 同 的 结构 体 ， 很 多 场 
合 下 是 允许 不 同 的 节点 拥有 相同 的 关键 字 的 (参见 图 7-8 中 的 key 成 员 ， 


它 作 为 无 符 写 整 型 数 时 表示 树 市 点 的 关键 字 〉 。 例 如 ， 不 同 的 字符 串 可 
能 会 散 列 出 相同 的 关键 字 ， 这 时 它们 在 红 黑 树 中 的 关键 字 是 相同 的 ， 然 
而 它们 又 是 不 同 的 节点 ， 这 样 在 添加 时 就 不 可 以 履 盖 原 有 同名 关键 字 节 
点 ， 而 是 作为 新 插入 的 节点 存在 。 因 此 ， 在 诬 加 元 素 时 ， 需 要 考虑 到 这 
种 情况 。 将 添加 元 素 的 方法 抽象 出 ngx_rbtree_insert_pt 函 数 指针 可 以 很 
好 地 实现 这 一 思想 ， 用 户 也 可 以 灵活 地 定义 自己 的 行为 。Nginx 帮 助 用 
户 实现 了 3 种 简单 行为 的 添加 节点 方法 ， 见 表 7-4。 











表 7-4 Noinx 为 红 黑 树 已 经 实现 好 的 3 种 数据 添加 方法 


方法 名 


执行 意义 
void ngx_rbtree_insert_value root 是 红 黑 树 容器 的 指针 ; node 是 待 可 红 黑 树 添 加 数据 节点 ， 每 个 
(ngx_rbtree_node t *root, 添加 元 素 的 ngx_rbtree_node t 成 员 的 指 | 数 据 节 点 的 关键 字 都 是 唯一 的 ， 
ngx rbtree node t *node, 针 ; sentinel 是 这 棵 红 黑 树 初始 化 时 哨兵 | 不 存在 同一 个 关键 字 有 多 个 节点 
ngx rbtree node t *sentinel) 节点 的 指针 的 问题 


root 是 红 黑 树 容器 的 指针 ; node 是 待 
添加 元 素 的 ngx_rbtree node t 成 员 的 | 向 红 黑 树 添加 数据 节点 ， 每 个 
了 针 ， 它 对 应 的 关键 字 是 时 间或 者 时 间 | 数据 节点 的 关键 字 表 示 时 间或 者 
差 ， 可 能 是 负数 ; sentinel 是 这 棵 红 黑 树 | 时 间 差 
初始 化 时 的 哨兵 节点 

root 是 红 黑 树 容 器 的 指针 ; node 是 待 可 红 黑 树 添 加 数据 节点 ， 每 个 
添加 元 素 的 ngx_str node t 成 员 的 指针 | 数据 节点 的 关键 字 可 以 不 是 唯一 
(ngx_rbtree_node t 类 型 会 强制 转化 为 | 的 , 但 它们 是 以 字符 串 作为 唯一 
ngx _str node t 类 型 ); sentinel 是 这 棵 红 | 的 标识 ， 存 放 在 ngx _ str node t 
黑 树 初始 化 时 哨兵 节点 的 指针 结构 体 的 str 成 员 中 


vold ngx rbtree insert timer value 





(ngx_ Ibtree node t *root, 
ngx rbtree node t *node, 


ngx rbtree node t *sentinel) 











Vold ngx str rbtree_ insert_ value 
(ngx rbtree node t *temp, 
ngx rbtree node t *node, 


ngx rbtree node t *sentinel) 


表 7-4 中 ngx_str_rbtree_insert_value 函 数 的 应 用 场景 为 : 节点 的 标识 
符 是 字符 串 ， 红 黑 树 的 第 一 排序 依据 仍然 是 节点 的 key 关 键 字 ， 第 二 排 
序 依据 则 是 节点 的 字符 串 。 因 此 ， 使 用 ngx_str_rbtree_insert_value 时 表 
示 红 黑 树 节点 的 结构 体 必 须 是 ngx_str_ node t， 如 下 所 示 。 








typedef struct { 
ngx_rbtree_node 上 node; 
ngx_str_t str; 
} ngx_str_node t; 





同时 ， 对 于 ngx_str_node_t 市 点 ，Nginx 还 提供 了 
ngx_str_rbtree_lookup 方 法 用 于 检索 红 黑 树 节 点 ， 下 面 来 看 一 下 它 的 定 
义 ， 代 码 如 下 。 





ngx_str_node t *ngx_str_rbtree lookup(ngx_rbtree t *rbtree, ngx_str_t *name, uint32 














其 中 ，hash 参 数 是 要 查询 节点 的 key 关 键 字 ， 而 name 是 要 查询 的 字 
符 串 (解决 不 同 字 符 串 对 应 相同 key 关 键 字 的 问题 ， 返 回 的 是 查询 到 
的 红 黑 树 节点 结构 体 。 





关于 红 黑 树 操 作 的 方法 见 表 7-5。 


表 7-5 ” 红 黑 树 容器 提供 的 方法 








方法 名 执行 意义 
tree 是 红 黑 树 容 器 的 指针 ; s 是 哨兵 | 初始 化 红 黑 树 ， 包括 初始 化 根 节 
ngx rbtree_init(tree, s, i) 节点 的 指针 ; i 是 ngx_rbtree_insert_pt | 点、 哨兵 节点 、negx_rbtree_insert_pt 
类 型 的 节点 添加 方法 ， 具体 见 表 7-4 | 节点 添加 方法 
void ngx_rbtree_insert(ngx_rbtree t| tree 是 红 黑 树 容器 的 指针 ; node 是 | 向 红 黑 树 中 添加 节点 ,该 方法 会 
*tree, ngx_rbtree_node t *node) 需要 添加 到 红 黑 树 的 节点 指针 通过 旋转 红 黑 树 保持 树 的 平 1 稀 
void ngx_rbtree_delete(ngx_rbtree t| tree 是 红 黑 树 容器 的 指针 ; node 是 | 从 红 黑 树 中 删除 节点 ， 该 方法 会 
*tree, ngx_rbtree_node t *node) 红 黑 树 中 需要 删除 的 节点 指针 通过 旋转 红 黑 树 保持 树 的 平衡 


在 初始 化 红 黑 树 时 ， 需 要 先 分 配 好 保存 红 黑 树 的 ngx_rbtree_t 结 构 
体 ， 以 及 ngx_rbtree_node t 类 型 的 哨兵 节点 ， 并 选择 或 者 自 定 义 
ngx_rbtree_insert_pt 类 型 的 节点 添加 函数 。 
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对 于 红 


想 了 解 如 何 使 用 红 黑 


dh 


果 只 是 


表 7-6 


方法 名 
node 7 
类 型 的 节点 


node : 


类 型 上 


ngx rbt red(node) 


是 乡 


ngx rbt black(node) 


#4 上 


节点 


ngx Ibt is_red(node) 


类 型 的 节点 





node 是 红 


ngx rbt is_black(node) 





类 型 


上 


nl1、n2 者 


node t 类 型 


和 节点 
ngx_ rbt_ copy_color(n1. n2) 


ngx rbtree node t* 


居 乡 





node 征 


ngx rbtree min 
类 型 的 节点 


(ngx_Ibtree node t *node, 
ngx rbtree node t *sentinel) 
node 


ngx_rbtree_sentinel init(node)|,,,, ,, .. 
局 了 类 型 的 节点 


表 7-5 中 的 方法 大 部 分 用 于 实现 或 者 扩展 红 
一 般 情 况 下 只 会 使 用 ngx_rbtree_min 方 法 。 


dy 


使 用 红 黑 树 ， 那 么 


本 区 
示例 。 


4 


7.5.4 ”使 用 红 


本 节 以 


是 红 


指针 


指针 


是 红 黑 树 中 mgx rbtree_ 
的 节点 指针 


树 的 哨兵 节 ， 


AT 加 
是 红 黑 





一 个 简单 的 例子 来 说 明 如 何 使 用 红 


树 的 每 个 节操 来 说 ， 它 们 都 具备 表 7-6 所 列 的 7 个 方法 ， 如 
树 ， 那 么 


只 需要 了 解 ngx_rbtree_min 方 法 。 


红 黑 树 节 点 提供 的 方法 


执行 意义 


黑 树 中 ngx rbtree node t|  、 和 
A EE 设置 node 节点 的 颜色 为 红色 


指针 


- 黑 树 中 msx rbtree hode f{ et 
二 3 设置 node 节点 的 颜色 为 黑色 


指针 


i wr 
AE = 


苦 node 节点 的 颜 色 为 红 色 人 则 返 回 十 0 
数值 ， 和 否则 返回 0 

若 node 节点 的 颜色 为 黑色 ， 则 返 
数值 ， 否 则 返回 0 


- 思 树 中 ngx_rbtree node { 


ngx rbtree node t 回 非 0 


黑 树 中 


将 n2 节点 的 颜色 复制 到 nl 节点 


- 黑 树 中 ngx_rbtree node ft 


指针 ; sentinel 是 这 棵 红 黑 


找到 当前 节点 及 其 子 树 中 的 最 小 节点 
(按照 key 关键 字 ) 


占 


该 节 点 


初始 化 哨兵 节点 ， 实 际 上 就 是 将 i 


颜色 置 为 黑色 


! 树 中 ngx_rbtree node { 


指针 


日 
征 





4 


树 的 功能 ， 如 果 只 


介绍 的 方法 或 者 结构 体 的 简单 用 法 的 实现 可 参见 7.5.4 节 的 相关 


树 的 简单 例子 


4 


树 容 嚣 。 首 先 在 栈 中 分 


配 rbtree 红 黑 树 容器 结构 体 以 及 哨兵 闻 点 sentinel (当然 ， 也 可 以 使 用 内 
存 池 或 者 从 进程 堆 中 分 配 ) ， 本 例 中 的 市 点 完全 以 key 关 键 字 作为 每 个 
节点 的 唯一 标识 ， 这 样 就 可 以 采用 预 设 的 ngx_rbtree_insert_value 方 法 
了 。 最 后 可 调用 ngx_rbtree_init 方 法 初始 化 红 黑 树 ， 代 码 如 下 所 示 。 





ngx_rbtree t rbtree; 
ngx_rbtree _ node t sentinel; 
ngx_rbtree_init(&rbtree, &sentinel, ngx_rbtree_ insert_value); 








本 例 中 树 节点 的 结构 体 将 使 用 7.5.3 节 中 介绍 的 TestRBTreeNode 结 构 
体 ， 树 中 的 所 有 节点 都 取 自 图 7-7， 每 个 元 素 的 key 关 键 字 按照 1、6、 
8、11、13、15、17、22、25、27 的 顺序 一 一 向 红 黑 树 中 添加 ， 代 码 如 
FH 








TestRBTreeNode rbTreeNode[10]; 


rbTreeNode[0].num = 1; 
rbTreeNode[1].num = 6; 
rbTreeNode[2].num = 8; 
rbTreeNode[3] .num = 11; 
rbTreeNode[4].num = 13; 
rbTreeNode[5],num = 15; 
rbTreeNode[6],num = 17; 
rbTreeNode[7],num = 22; 
rbTreeNode[8] ,num = 25; 


rbTreeNode[9] ,num 
for (i = 0; i < 10; i++) 


rbTreeNode[i].node.key = rbTreeNode[i].num; 
ngx_rbtree_insert(&rbtree,é&rbTreeNode[i].node); 





以 这 种 顺序 添加 完 的 红 黑 树 形态 如 图 7-7 所 示 。 如 果 需 要 找 出 当前 
红 黑 树 中 最 小 的 节点 ， 可 以 调用 ngx_rbtree_min 方 法 获取 。 





ngx_rbtree node t *tmpnode = ngx_rbtree min(rbtree.root, &sentinel); 





当然 ， 参 数 中 如 宋 不 使 用 根 节点 而 是 使 用 任 一 个 节点 也 古 可 以 的 。 
下 面 来 看 一 下 如 何 检索 1 个 节点 ， 虽 然 Nginx 对 此 并 没有 提供 预 设 的 方法 
( 仅 对 字符 串 类 型 提供 了 ngx_str_rbtree_lookup 检 索 方 法 ) ， 但 实际 上 检 
索 古 非常 简单 的 。 下 面 以 寻找 key 关 键 字 为 13 的 节操 为 例 来 加 以 说 明 。 





ngx_uint_t lookupkey = 13; 
tmpnode = rbtree.root,; 
TestRBTreeNode *lookupNode; 
while (tmpnode != &sentinel) { 
if (lookupkey != tmpnode->key) { 
// 根据 


key 关 键 字 与 当前 节点 的 大 小 比较 ， 决 定 是 检索 左 子 树 还 是 右 子 树 


tmpnode = (lookupkey < tmpnode->key) tmpnode->left : tmpnode->right; 
continue,; 


} 
// 找到 了 值 为 


13 的 树 节点 


lookupNode = (TestRBTreeNode *) tmpnode,; 
break; 


} 





从 红 黑 树 中 删除 1 个 节点 也 是 非常 简单 的 ， 如 把 刚刚 找到 的 值 为 13 
的 节点 从 rbtree 中 删除 ， 只 需 调 用 ngx_rbtree_delete 方 法 。 





ngx_rbtree_delete(&rbtreey&lookupNode->node ) ; 








7.5.5 ”如何 目 定义 添加 成 员 方 法 








由 于 市 点 的 key 天 键 字 必 须 是 整 型 ， 这 导致 很 多 情况 下 不 同 的 节操 
会 具有 相同 的 key 关 键 字 。 如 果 不 希 望 出 现 具有 相同 key 关 键 字 的 不 同市 
点 在 同 红 黑 树 添加 时 出 现 履 兰 原 节点 的 情况 ， 就 再 要 实现 目 有 的 


ngx_rbtree_insert_pt 方 法 。 





许多 Nginx 模 块 在 使 用 红 黑 树 时 都 目 定 义 了 ngx_rbtree_insert_pt 方 法 
(如 geo、filecache 模 块 等 ) ， 本 节 以 7.5.3 节 中 介绍 过 的 
ngx_str_rbtree_insert_value 为 例 ， 来 说 明 如 何 定 义 这 样 的 方法 。 先 看 一 
下 ngx_str_rbtree_insert_value 的 实现 。 代 码 如 下 。 





void 
ngx_str_rbtree_ insert_ value(ngx_rbtree node t *temp, 
ngx_rbtree _ node t *node, ngx_rbtree node t *sentinel) 





{ 
ngx_str_node_t i 芝 生 
ngx_rbtree node t **p; 
for (;; ){ 


n = (ngx_str_node t *) node; 
t = (ngx_str_node t *) temp; 
// 首先 比较 


key 关 键 字 ， 红 黑 树 中 以 


key 作 为 第 一 索引 关键 字 


if (node->key != temp->key) { 
// 左 子 树 节点 的 关键 节 小 于 右 子 树 


p = (node->key < temp->key) &temp->left : &temp->right 


Ay 当 


key 关 键 字 相 同时 ， 以 字符 串 长 度 为 第 二 索引 关键 字 


else if (n->str.len != t->str.len) { 


// 左 子 树 节点 字符 串 的 长 度 小 于 右 子 树 


p = (n->str.len < t->str.len) &temp->left : &temp->right; 
} else { 
// key 关 键 字 相 同 且 字 符 串 长 度 相 同时 ， 再 继续 比较 字符 串 内 容 


p = (ngx_memcmp(n->str.data, t->str.data, n->str.len) < 0) &temp->left 


// 如 果 当 前 节点 


p 是 哨兵 节点 ， 那 么 跳出 循环 准备 插入 节点 


if (*p == sentinel) { 
break; 


} 
// p 节 点 与 要 插入 的 节点 具有 相同 的 标识 符 时 ， 必 须 履 盖 内 容 


temp = *p; 


*p = node; 
// 置 插入 节点 的 父 节点 


node->parent = temp; 
// 左右 子 节点 都 是 哨兵 节点 


node->left = Sentinel， 
node->right = sentinel,; 
/* 将 节点 颜色 置 为 红色 。 注 意 ， 红 黑 树 的 


ngx_rbtree_insert 方 法 会 在 可 能 的 旋转 操作 后 重 置 该 节点 的 颜色 





*/ 
ngx_rbt_red(node); 





可 以 看 到 ， 该 代码 与 7.5.4 市 中 介绍 过 的 检索 节点 代码 很 相似 。 它 所 
要 处 理 的 主要 问题 就 是 当 key 关 键 字 相 同时 ， 继 续 以 何 种 数据 结构 作为 
标准 来 确定 红 黑 树 节 点 的 唯一 性 。Nginx 中 已 经 实现 的 诸多 


ngx_rbtree_insert_pt 方 法 都 是 非常 相似 的 ， 读 者 完全 可 以 参照 
ngx_str_rbtree_insert_value 方 法 来 自 定义 红 黑 树 节 点 添加 方法 。 


7.6 ngx_radix_tree_t 基 数 树 


基数 树 也 是 一 种 二 又 碍 找 树 ， 然 而 它 却 不 像 红 黑 树 一 样 应 用 广泛 
(目前 官方 模块 中 仅 geo 模 块 使 用 了 基数 树 ) 。 这 是 因为 

ngx_radix_tree_t 基 数 树 要 求 存储 的 每 个 节点 都 必须 以 32 位 整 型 作为 区 别 
任意 两 个 节点 的 唯一 标识 ， 而 红 黑 树 则 没有 此 要 求 。ngx_radix_tree_t 基 
数 树 与 红 黑 树 不 同 的 另 一 个 地 方 : ngx_radix_tree_t 基 数 树 会 负责 分 配 每 
个 而 上 占用 的 内 存 。 因 此 ， 每 个 基数 树 节 点 也 不 再 像 红 黑 树 中 那么 灵活 
可 以 是 任意 包含 ngx_rbtree_node t 成 员 的 结构 体 。 基 数 树 的 每 个 节 
点 中 可 以 存储 的 值 只 是 1 个 指针 ， 它 指 同 实际 的 数据 。 








本 节 将 以 一 棵 完整 的 ngx_radix_tree_t 基 数 树 来 说 明基 数 树 的 原理 和 
用 法 ， 这 棵 树 的 深度 为 9， 它 包括 以 下 4 个 节点 : 0X20000000、 
0X40000000、0X80000000、0Xc0000000。 这 里 书写 成 十 六 进 制 是 为 了 
便于 理解 ， 因 为 基数 树 实 际 是 按 二 进 制 位 来 建立 树 的 ， 上 面 4 个 节点 如 
果 转 换 为 十 进 制 无 符号 整 型 〈 也 就 是 7.6.3 节 例子 中 的 ngx_uint t) ， 它 
们 的 值 分 别 是 536870912、1073741824、2147483648、2684354560; 如 
果 转 换 为 二 进 制 ， 它 们 的 值 分 别 为 : 
00100000000000000000000000000000、 





01000000000000000000000000000000、 
10000000000000000000000000000000、 


11000000000000000000000000000000。 在 图 7-9 中 ， 可 以 看 到 这 4 个 节点 
如 何 存储 到 深度 为 3 的 基数 树 中 。 


7.6.1 ngx_radix_tree_t 基 数 树 的 原理 


基数 树 具 备 二 又 碍 找 树 的 所 有 优点 : 基本 操作 速度 快 〈 如 检索 、 插 
入 、 删 除 节 点) 、 文 持 范 围 得 询 、 文 持 遇 历 操作 等 。 但 基数 树 不 像 红 黑 
树 那样 会 通过 目 身 的 旋转 来 达到 平衡 ， 基 数 树 是 不 管 树 的 形态 是 否 平衡 
的 ， 因 此 ， 它 插入 节点 、 删 除 节 点 的 速度 要 比 红 黑 树 快 得 多 ! 那么 ， 基 
数 树 为 什么 可 以 不 管 树 的 形态 是 否 平 衡 呢 ? 





红 黑 树 是 通过 不 同 节点 间 key 关 键 字 的 比较 来 决定 树 的 形态 ， 而 基 
数 树 则 不 然 ， 它 每 一 个 节点 的 key 关 键 字 已 经 决定 了 这 个 节点 处 于 树 中 
的 位 置 。 决 定 节点 位 置 的 方法 很 简单 ， 先 将 这 个 节点 的 整 型 关键 字 转 化 
为 二 进 制 ， 从 左 向 右 数 这 32 个 位 ， 遇 到 0 时 进入 左 子 树 ， 遇 到 1 时 进入 右 
子 树 。 因 此 ，ngx_radix tree_t 树 的 最 大 深度 是 32。 有 时 ， 数 据 可 能 仅 在 
全 部 整 型 数 范围 的 某 一 小 段 中 ， 为 了 减少 树 的 高 度 ，ngx_radix_tree_t 义 
加 入 了 掩 码 的 概念 ， 掩 码 中 为 1 的 位 节点 关键 字 中 有 效 的 位 数 同 时 也 决 
定 了 树 的 有 效 高 度 。 例 如 ， 掩 码 为 
11100000000000000000000000000000 (也 就 是 0Xe0000000〉 时 ， 表 示 树 
的 高 度 为 ?3。 如 果 1 个 节点 的 关键 字 为 0XOfffffff， 那 么 实际 上 对 于 这 棵 基 
数 树 而 言 ， 它 的 节点 关键 字 相 当 于 0X00000000， 因 为 掩 码 决定 了 仅 前 3 














位 有 效 ， 并 且 它 也 只 会 放 在 树 的 第 三 层 节 点 中 。 


如 图 7-9 所 示 ，0X20000000 这 个 节点 插 到 基数 树 后 ， 由 于 掩 码 是 
0Xe0000000， 因 此 它 决 定 了 所 有 的 节点 都 将 放 在 树 的 第 三 层 。 下 面 结合 
掩 码 看 看 节点 是 如 何 根据 关键 字 来 决定 其 在 树 中 的 位 置 的 。 掩 码 中 有 3 
个 1， 将 节点 的 关键 字 0X20000000 转 化 为 二 进 制 再 取 前 3 位 为 001， 然 后 
分 3 步 决 定 节点 的 位 置 。 





. 首先 找到 根 节 点 ， 取 010 的 第 1 位 0， 表 示 选 择 左 子 树 。 


第 2 位 为 0， 表 示 再 选择 左 子 树 。 


第 3 位 为 1， 表 示 再 选择 右 子 树 ， 此 时 的 节点 就 是 第 三 层 的 节 


这 时 会 用 它 来 存储 0X20000000 这 个 节点 。 


ngx radix tree t 


十 SiZe 

+ngx radix tree create () 
t+ngx radix32 tree _insert () 
+ngx radix32 tree delete () 
+ngx radix32 tree find() 


用 户 自 定义 的 数据 结构 





ngx radix node tt 市 点 


1 


图 7-9 3 层 基 数 树 示意 图 
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ngx_radix_tree_t 基 数 树 的 每 个 节点 由 ngx_radix_node_t 结 构 体 表示 ， 
代码 如 下 所 示 。 





typedef struct ngx_radix_node s ngx_radix_node_t,; 
struct ngx_radix_node_s 


// 指向 右 子 树 ， 如 果 没 有 右 子 树 ， 则 值 为 





null 空 指针 


ngx_radix_node t *right; 
// 指向 左 子 树 ， 如 果 没 有 左 子 树 ， 则 值 为 


null 空 指针 


ngx_radix_node t *left; 
// 指向 父 节点 ， 如 果 没 有 父 节 点 ， 则 (如 根 节点 ) 值 为 


null 空 指针 


ngx_radix_node t *parent; 
/*ValUue 存 储 的 是 指针 的 值 ， 它 指向 用 户 定义 的 数据 结构 。 如 果 这 个 节点 还 未 使 用 ， 


Value 的 值 将 是 


NGX_RADIX_NO_VALUE */ 
uintptr_t Value 


}; 





如 图 7-9 所 示 ，value 字 上 段 指 同 用 户 自 定义 的 、 有 意义 的 数据 结构 。 
另外 ， 基 数 树 也 不 像 红 黑 树 一 样 还 有 哨兵 和 节点。 基数 树 节 点 的 left 和 
right 都 是 有 可 能 为 null 空 指针 的 。 





与 红 黑 树 不 同 的 是 ， 红 黑 树 容器 不 负责 分 配 每 个 树 节 点 的 内 存 ， 而 
ngx_radix_tree_t 其 数 树 则 会 分 配 hngx_radix_node_t 结 构 体 ， 这 样 使 用 
ngx_radix_node_t 基 数 树 时 就 会 更 简单 一 些 。 但 ngx_radix_node_t 基 数 树 
是 如 何 管理 这 些 ngx_radix_node_t 结 构 体 的 内 存 呢 ? 下 面 来 看 一 下 
ngx_radix_node_t 容 器 的 结构 ， 代 人 码 如 下 。 





typedef struct { 
// 指向 根 节点 


ngx_radix_node t *root; 
// 内 存 池 ， 它 负责 给 基数 树 的 节点 分 配 内 存 


ngx_pool 七 *pool; 
/* 管 理 已 经 分 配 但 暂时 未 使 用 (不 在 树 中 ) 的 节点 ， 


free 实 际 上 是 所 有 不 在 树 中 节点 的 单 链表 


*/ 
ngx_radix_node t *free; 
// 己 分 配 内 存 中 还 未 使 用 内 存 的 首 地 址 


char *start,; 
// 已 分 配 内 存 中 还 未 使 用 的 内 存 大 小 


size_t size; 
} ngx_radix_ tree_t; 





上 面 的 pool 对 象 用 来 分 配 内 存 。 每 次 删除 1 个 节点 时 ， 
ngx_radix_tree_t 基 数 树 并 不 会 释放 这 个 节点 占用 的 内 存 ， 而 是 把 它 添加 
到 free 单 链表 中 。 这 样 ， 在 添加 新 的 市 点 时 ， 会 首先 伍 看 free 中 是 否 还 有 
节点 ， 如 宁 free 中 有 未 使 用 的 节点 ， 则 会 优先 使 用 ， 如 果 没 有 ， 就 会 再 
从 pool 内 存 池 中 分 配 新 内 存 存储 节点 。 


对 于 ngx_radix_tree_t 结 构 体 来 说 ， 仅 从 使 用 的 角度 来 看 ， 我 们 不 需 
要 了 解 pool、free、start、size 这 些 成 员 的 意义 ， 仅 了 解 如 何 使 用 root 根 
节点 即 可 。 





7.6.2 ”基数 树 的 使 用 方法 


相 比 于 红 黑 树 ，ngx_radix_tree_t 基 数 树 的 使 用 方法 要 简单 许多 ， 
需 表 7-7 中 列 出 的 4 个 方法 即 可 简单 地 操作 基数 树 。 


表 7-7 Dox_fadix_tfee_t 基 


方法 名 


ngx radix tree t *ngx Iadlx_tree_create 


(ngx_pool t *pool, 
ngx_int t preallocate) 


ngx int tngx radix32tree insert 
(ngx_ radix_ tree t *tree, 

uint32_t key, 

uint32_t mask, 

uintptr_t value) 


方法 名 


ngx int tngx radix32tree_ delete 
(ngx radix tree t *tree, 
uint32_t key, uint32_t mask) 


uintptr t ngx radix32tree find 
(ngx radix tree t *tree, 
uint32_t key) 





pool 是 内 存 池 指针 ， 
分 配 的 基数 树 节 点 数 ， 如 果 传 递 的 值 
为 -1， 那 么 将 会 根据 当前 操作 系统 中 
-个 页 面 的 大 小 来 预 分 配 基数 树 节 点 


preallocate 是 预 


tree 是 ngx radix tree t 基数 树 结构 
体 的 指针 ，key 是 待 插入 节点 的 关键 
字 ，mask 为 关键 字 掩 码 (决定 key 关 
键 字 有 效 位 数 以 及 树 的 深度 )，value 
是 这 个 关键 字 对 应 数据 结构 的 指针 


tree 是 ngx radix tree t 基数 树 结构 
体 的 指针 ，key 是 待 删除 节点 的 关键 
字 ，mask 为 tas 码 (决定 key 关 
键 字 有 效 位 数 


tree 是 ngx_radix_ tree t 基 数 树 结构 
体 的 指针 ，key 是 待 查询 节点 的 关键 字 


7.6.3 ”使 用 基数 树 的 例子 


本 节 以 图 7-9 中 的 基数 树 为 例 来 构造 


基数 树 提 供 的 方法 


执行 意义 

用 来 创建 ngxradix tree t 基 
数 树 。 如 果 创 建成 功 ， 则 返回 
ngx radix tree t 结 构 体 的 指针 ; 
如 果 失 败 ， 则 返回 NULL 空 指针 

表示 向 基数 树 中 插 人 1 个 节 
点 。 如 果 成 功 ， 则 返回 NGX_ 
OK ; 如 果 内 存 池 中 无 法 分 配 
足够 的 空间 ， 则 返回 NGX_ 
ERROR ; 如 果 掩 码 设置 错误 ， 
则 可 能 返回 NGX_BUSY 


NS 
Xt 


执行 意义 
表示 从 基数 树 中 删除 1 个 节 
点 。 如 果 删 除 成 功 ， 则 返回 


NGX_OK ; 如 果 删 除 失败 ， 则 
返回 NGX_ ERROR 
表示 在 基数 树 中 查询 1 个 地 


点 ， 对 于 攻 回 的 Se t 类 . 
的 指针 地 址 ， 可 以 将 其 强制 转 
化 为 实际 数据 结构 的 指 针 来 使 
用 。 如 果 没 有 查询 到 ， 则 会 返 
加 NGX RADIX NO VALUE 


告 radixTree 这 棵 基数 树 。 首 先 ， 


使 用 ngx_radix_tree_create 方 法 创建 基数 树 ， 代 码 如 下 。 





ngx_radix_tree _t * radixTree 





ngx_radix_tree create(cf->pool, -1); 


将 预 分 配 节 点 简单 地 设置 为 -1， 这 样 pool 内 存 池 中 就 会 只 使 用 1 个 
页 面 来 尽 可 能 地 分 配 基 数 树 节点 。 接 下 来 ， 按 照 图 7-9 构 造 4 个 市 点 数 
据 ， 这 里 将 它们 所 使 用 的 数据 结构 简单 地 用 无 符 写 整 型 表示 ， 当 然 ， 实 
际 使 用 时 可 以 是 任意 的 数据 结构 。 





ngx_uint_t testRadixValue1 = Ox20000000; 
ngx_uint_t testRadixValue2 = Ox40000000; 
ngx_uint_t testRadixValue3 = Ox80000000; 
ngx_uint_t testRadixValue4 = Oxa0000000; 





接 下 来 将 上 述 节点 添加 到 radixTree 基 数 树 中 ， 注 意 ， 掩 码 是 
0xe0000000。 





Int rc; 
rc = ngx_radix32tree_insert(radixTree, 

Ox20000000, Qxe0000000, (uintptr_t)&testRadixValuel1); 
rc = ngx_radix32tree_insert(radixTree, 

Ox40000000, Qxe0000000, (uintptr_t)&testRadixValue2); 
rc = ngx_radix32tree_insert(radixTree, 

Ox80000000, Qxe0000000, (uintptr_t)&testRadixValue3); 
rc = ngx_radix32tree_insert(radixTree, 

0xa0000000，0xe0000000， (uintptr_t)&testRadixValue4); 





下 面 来 试 着 调用 ngx_radix32tree_find 查 询 节 点 ， 代 码 如 下 。 





ngx_uint_t* pRadixValue = (ngx_uint t *) ngx_radix32tree find( radixTree, Ox800000( 





注意 ， 如 有 果 没 有 得 询 到 ， 那 么 返回 的 pRadixValue 将 会 是 


NGX_ RADIX_ NO_VALUE. 


下 面 调用 ngx_radix32tree_delete 删 除 1 个 节点 ， 代 人 码 如 下 。 





rc = ngx_radix32tree_delete(radixTree，0xa0000000，0xe0000000 ) ; 


aa 


7.7 文 持 通配符 的 散 列 表 


散 列 表 (也 叫 哈 希 表 )〉 是 典型 的 以 空间 换 时 间 的 数据 结构 ， 在 一 些 
合理 的 假设 下 ， 对 任意 元 素 的 检索 、 插 入 速度 的 期 望 时 间 为 0(1)， 这 种 
高 效 的 方式 非常 适合 频 楷 读 取 、 插 入 、 删 除 元 隶 ， 以 及 对 速度 敏感 的 场 
合 。 因 此 ， 散 列表 在 以 效率 、 性 能 赣 称 的 Nginx 服 务 器 中 得 到 了 广泛 的 
应 用 。 








注意 ，Nginx 不 只 提供 了 基本 的 散 列 表 。Nginx 作 为 一 个 Web 服 务 
器 ， 它 的 各 种 散 列 表 中 的 关键 字 多 以 字符 串 为 主 ， 特 别 是 URI 域 名 ， 如 
www.test.com 。 这 时 一 个 基本 的 要 求 就 出 现 了 ， 如 何 让 散 列 表 支 持 通 配 
符 呢 ?” 前 面 在 2.4.1 节 中 介绍 了 nginx.conf 中 主机 名 称 的 配置 ， 这 里 的 主 
机 域名 是 允许 以 * 作 为 通配符 的 ， 包 括 前 置 通配符 ， 如 *.test.com， 或 者 
后 置 通配符 ， 如 www.test.*。Nginx 封 装 了 ngx_hash_combined_t 容 器 ， 专 
门 针 对 URI 域 名 支持 前 置 或 者 后 置 的 通配符 (不 支持 通配符 在 域名 的 中 
国 上 和 








本 节 会 以 一 个 完整 的 通配符 散 列 表 为 例 来 说 明 这 个 容 喜 的 用 法 。 


7.7.1 ngx_hash_t 基 本 散 列表 








散 列 表 是 根据 元 系 的 关键 码 值 而 直接 进行 访问 的 数据 结构 。 也 就 是 


说 ， 它 通过 把 关键 码 值 映 射 到 表 中 一 个 位 置 来 访问 记录 ， 以 加 快 奏 找 的 
速度 。 这 个 映射 函数 fy 作 散 列 方法 ， 存 放 记 录 的 数组 叫做 散 列 表 。 


大 结构 中 存在 关键 字 和 K 相 等 的 记录 ， 则 必定 在 f(K) 的 存储 位 置 
上 。 由 此 ， 不 需要 比较 便 可 直接 取得 所 查 记录 。 我 们 称 这 个 对 应 关系 f 
为 散 列 方法 ， 按 这 个 思想 建立 的 表 则 为 散 列 表 。 


对 于 不 同 的 关键 字 ， 可 能 得 到 同一 散 列 地 址 ， 即 关键 码 
key1zkey2， 而 f(key1l)=f(key2)， 这 种 现象 称 为 碰撞 。 对 该 散 列 方法 来 
说 ， 具 有 相同 函数 值 的 关键 字 称 作 同 义 词 。 综 上 所 述 ， 根 据 散 列 方法 
H(key) 和 人 处理 碰 撞 的 方法 将 一 组 关键 字 映 象 到 一 个 有 限 的 连续 的 地 址 集 
(区 间 〉 上 ， 并 以 关键 字 在 地 址 集中 的 “ 象 ”作为 记录 在 表 中 的 存储 位 
置 ， 这 种 表 便 称 为 散 列表 ， 这 一 映 象 过 程 称 为 散 列 造 表 或 散 列 ， 所 得 的 
存储 位 置 称 为 散 列 地 址 。 





在 对 于 关键 字 集 合 中 的 任 一 个 关键 字 ， 经 散 列 方法 映 象 到 地 址 集合 
中 任何 一 个 地 址 的 概率 是 相等 的 ， 则 称 此 类 散 列 方法 为 均匀 散 列 方法 ， 
这 就 使 关键 字 经 过 散 列 方法 得 到 了 一 个 “随机 的 地 址 ”从 而 减少 了 碰 


撞 。 





1. 如 何 解决 碰撞 问题 


如 果 得 知 散 列表 中 的 所 有 元 系 ， 那 么 可 以 设计 出 “完美 ”的 散 列 方 





法 ， 使 得 所 有 的 元 系 经 过 f(K) 散 列 方法 运算 后 得 出 的 值 都 不 同 ， 这 样 就 
避免 了 碰撞 问题 。 然 而 ， 通 用 的 散 列 表 是 不 可 能 预知 散 列 表 中 的 所 有 元 
素 的 ， 这 样 ， 通 用 的 散 列 表 都 需要 解决 伴 撞 问题 。 


当 散 列表 出 现 碰撞 时 要 如 何 解决 呢 ? 一 般 有 两 个 简单 的 解决 方法 : 
分 离 链接 法 和 开放 寻 址 法 。 


分 离 链 接 法 ， 残 是 把 散 列 到 同一 个 权 中 的 所 有 元 素 都 放 在 散 列 表 外 
的 一 个 链表 中 ， 这 样 碍 询 元 素 时 ， 在 找到 这 个 槽 后 ， 还 得 过 有 历 链 表 才 能 
找到 正确 的 元 素 ， 以 此 来 解雇 碰撞 问题 。 








开放 寻 址 法 ， 即 所 有 元 素 都 存放 在 散 列 表 中 ， 当 碍 找 一 个 元 素 时 ， 
要 检查 规则 内 的 所 有 的 表 项 《〈 例 如， 连续 的 非 空 槽 或 者 整个 空间 内 符合 
散 列 方法 的 所 有 槽 》， 下 到 找到 所 需 的 元 素 ， 或 者 最 终 发 现 元 系 不 在 表 
中 。 开 放 寻 址 法 中 没有 链表 ， 也 没有 元 系 存 放 在 散 列 表 外 。 











Nginx 的 散 列 表 使 用 的 是 开放 寻 址 法 。 





开放 寻 址 法 有 许多 种 实现 方式 ，Nginx 使 用 的 是 连续 非 空 槽 存储 碰 
撞 元 素 的 方法 。 例 如 ， 当 插入 一 个 元 素 时 ， 可 以 按照 散 列 方法 找到 指定 
槽 ， 如 果 该 槽 非 空 旦 其 存储 的 元 素 与 竺 插入 元 素 并 非 同一 元 素 ， 则 依次 
检查 其 后 连续 的 槽 ， 直 到 找到 一 个 空 槽 来 放置 这 个 元 素 为 止 。 碍 询 元 妹 
时 也 是 使 用 类 似 的 方法 ， 即 从 散 列 方法 指定 的 位 置 起 检查 连续 的 非 空 模 
中 的 元 系 。 





2.ngx_hash_t 散 列表 的 实现 


对 于 散 列 表 中 的 元 素 ，Nginx 使 用 ngx_hash_elt_t 结 构 体 来 存储 。 下 
面 看 一 下 ngx_hash_elt_t 的 成 员 ， 代 码 如 下 。 





typedef struct { 
/* 指 向 用 户 自 定义 元 素数 据 的 指针 ， 如 果 当 前 


ngx_hash_elt_t 档 为 空 ， 则 


Value 的 值 为 


© */ 
void *value; 
/* 元 素 关键 字 的 长 度 


u_short 
// 元 素 关键 字 的 首 地 址 


u_char name[1]; 
} ngx_hash_elt_t; 





每 一 个 散 列 表 槽 都 由 1 个 ngx_hash_elt_t 结 构 体 表示 ， 当 然 ， 这 个 模 
的 大 小 与 ngx_hash_elt_t 结 构 体 的 大 小 《也 就 是 sizeof(ngx_hash_elt_b) 
是 不 相等 的 ， 这 是 因为 name 成 员 只 用 于 指出 关键 字 的 首 地 址 ， 而 关键 字 
的 长 度 是 可 变 长 度 。 那 么 ， 一 个 槽 究竟 占用 多 大 的 空间 呢 ? 其 实 这 是 在 
初始 化 散 列 表 时 决定 的 。 基 本 的 散 列 表 由 ngx_hash_t 结 构 体 表示 ， 如 下 
所 示 。 











typedef struct 
// 指向 散 列 表 的 首 地 址 ， 也 是 第 


1 个 楷 的 地 址 


ngx_hash elt t **buckets; 
// 散 列表 中 楼 的 总 数 


ngx_uint_t size,; 
} ngx_hash_t; 








因此 ， 在 分 配 buckets 成 员 时 就 决定 了 每 个 槽 的 长 度 〈 限 制 了 每 个 元 
素 关 键 字 的 最 大 长 度 ) ， 以 及 整个 散 列 表 所 占用 的 空间 。 在 7.7.2 市 中 将 
会 介绍 Nginx 提 供 的 散 列 表 初 始 化 方法 。 


如 图 7-10 所 示 ， 散 列表 的 每 个 槽 的 首 地 址 都 是 ngx_hash_elt_t 纺 构 
体 ，value 成 员 指 癌 用 户 有 意义 的 结构 体 ， 而 len 是 当前 这 个 槽 中 
name《 也 惑 是 元 聚 的 关键 字 ) 的 有 效 长 度 。ngx_hash_t 散 列表 的 buckets 
指向 了 散 列 表 的 起 始 地 址 ， 而 size 指 出 散 列 表 中 横 的 总 数 。 











ngx hash t 





ngx hash elt tt 
+value 
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+ size 


Fngx hash find () 






+len 
+name 
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Name 





ngx hash elt 1 












共有 size 个 ngx hash_elt t 结构 体 


图 7-10 ngx_hash_t 基 本 散 列 表 的 结构 示意 图 


ngx_hash_t 散 列表 还 提供 了 ngx_hash_find 方 法 用 于 查询 元 素 ， 下 面 
党 来 看 二 下 它 的 定义。 


void *ngx_hash_find(ngx_hash_t *hash, ngx_uint_t key, u_char *name, size_t len) 








其 中 ， 参 数 hash 是 散 列 表 结 构 体 的 指针 ， 而 key 则 是 根据 散 列 方法 
算出 来 的 散 列 关键 字 ，name 和 len 则 表示 实际 关键 字 的 地 址 与 长 度 。 
ngx_hash_find 的 执行 结果 就 是 返回 散 列 表 中 关键 字 与 name、len 指 定 关 
键 字 完全 相同 的 槽 中 ，ngx_hash_elt_t 结 构 体 中 value 成 员 所 指向 的 用 户 
数据 。 如 果 ngx_hash_find 没 有 查询 到 这 个 元 素 ， 就 会 返回 NULL。 


3.ngx_hash_t 的 散 列 方法 


Nginx 设 计 了 ngx_hash_key_pt 散 列 方法 指针 ， 也 就 是 说 ， 完 全 可 以 
按照 ngx_hash_key_pt 的 函数 原型 自 定 义 散 列 方法 ， 如 下 所 示 。 





typedef ngx_uint t (*ngx_hash_key_pt) (u_char *data, size t len); 








其 中 ， 传 入 的 data 是 元 素 关 键 字 的 首 地 址 ， 而 len 是 元 素 关 键 字 的 长 
度 。 可 以 把 任意 的 数据 结构 强制 转换 为 u_char* 并 传 给 ngx_hash_key_pt 
散 列 方法 ， 从 而 决定 返回 什么 样 的 散 列 整 型 关键 码 来 使 碰撞 率 降 低 。 


当然 ，Nginx 也 提供 了 两 种 基本 的 散 列 方法 ， 它 会 假定 关键 字 是 字 





符 串 。 如 末 关 键 字 确实 是 字符 串 ， 那 么 可 以 使 用 表 7-8 提 供 的 散 列 方 
2 





表 7-8 Nginx 提 供 的 两 种 散 列 方法 





散 列 方法 意 义 
ngx uint tngx hash key(u char *data, size t len) 使 用 BKDR 算法 将 任意 长 度 的 字符 串 映射 为 整 型 
将 字符 串 全 小 写 后 ， 再 使 用 BKDR 算法 将 任意 长 度 的 字 


ngx uint tngx hash key lc(u char *data, slze_t len) 








符 串 映射 为 整 型 





这 两 种 散 列 方法 的 区 别 仅 仅 在 于 ngx_hash_key_lc 将 关键 字 字符 串 全 
小 写 后 再 调用 ngx_hash_key 来 计算 关键 但 。 


7.7.2” 文 持 通 配 符 的 散 列 表 


如 果 散 列表 元 素 的 关键 字 是 URI 域 名 ，Nginx 设 计 了 支持 简单 通 配 
符 的 散 列 表 ngx_hash_combined_t， 那 么 它 可 以 支持 简单 的 前 置 通配符 或 
者 后 置 通配符 。 


1. 原 理 





所 谓 支 持 通配符 的 散 列 表 ， 就 是 把 基本 散 列 表 中 元 素 的 关键 字 ， 用 
去 除 通 配 符 以 后 的 字符 作为 关键 字 加 入 ， 原 理 其 实 很 简单 。 例 如 ， 对 于 
关键 字 为 “www.test.*” 这 样 带 通 配 符 的 情况 ， 直 接 建立 一 个 专用 的 后 置 
通配符 散 列 表 ， 存 储 元 素 的 关键 字 为 www.test。 这 样 ， 如 果 要 检索 
www.test.cn 是 否 匹 配 www.test.*， 可 用 Nginx 提 供 的 专用 方法 








ngx_hash_find_wc_tail 检 索 ，ngx_hash_find_wc_tail 方 法 会 把 要 查询 的 
www.test.cn 转 化 为 www.test 字 符 串 再 开始 查询 。 





同样 ， 对 于 关键 字 为 “*.test.com” 这 样 带 前 置 通配符 的 情况 ， 也 直接 
建立 了 一 个 专用 的 前 置 通配符 散 列表 ， 存 储 元 素 的 关键 字 为 com .test.。 
如 果 我 们 要 检索 smtp.test.com 是 否 匹 配 *.test.com， 可 用 Nginx 提 供 的 专用 
方法 ngx_hash_find_wc_head 检 索 ，ngx_hash_find_wc_head 方 法 会 把 要 查 
询 的 smtp.test.com 转 化 为 com.test. 字 符 串 再 开始 查询 (如 图 7-11 所 示 〉。 


nex_hash _wildcard 1 
+ hash: nex _hash _1 
+ value : char 


+nex_hash _ find_wcec _head 0 





+nex_hash _find _we _taill (0) 


图 7-11 ngx_hash_wildcard_t 基 本 通配符 散 列 表 





Nginx 封 装 了 ngx_hash_wildcard_t 结 构 体 ， 专 用 于 表示 前 置 或 者 后 置 
通配符 的 散 列 表 。 





typedef struct { 
// 基本 散 列表 


ngx_hash_t hash 
/* 当 使 用 这 个 


ngx_hash_wildcard t 通 配 符 散 列表 作为 某 容 器 的 元 素 时 ， 可 以 使 用 这 个 


Value 指针 指向 用 户 数据 


< 
void *Value 
} ngx_hash_wildcard t; 





实际 上 ，ngx_hash_wildcard_t 只 是 对 ngx_hash_t 进 行 了 简单 的 封 
装 ， 所 加 的 value 指 针 其 用 途 也 是 多 样 化 的 。ngx_hash_wildcard _t 同 时 提 
供 了 两 种 方法 ， 分 别 用 于 查询 前 置 或 者 后 置 通配符 的 元 素 ， 见 表 7-9。 











表 7-9 ngx_hash_wildcard_t 提 供 的 方法 










方法 原型 
void *ngx_hash find we_ head hwc 是 散 列表 的 指针 ，name| 将 待 查 询 关 键 字 name 转换 为 前 置 散 列表 规 
(ngx_ hash wildcard t *hwec， 是 待 查 询 关 键 字 ，len 是 待 查询 | 则 下 的 字符 串 再 递归 查询 ， 成 功 时 会 返回 找到 













u_char *name. size_t len) 关键 字 的 长 度 元 素 所 指 回 的 用 户 数据 ， 和 否则 返回 NULL 
void *ngx_hash find we tail hwc 是 散 列 表 的 指针 ，name| 将 待 查询 关键 字 name 转换 为 后 置 散 列 表 规 


(ngx_hash wildcard t *hwc， 是 待 查询 关键 字 ，len 是 待 查询 的 字符 串 再 递归 查询 ， 成 功 时 会 返回 找到 


u_char *name, size_t len) 关键 字 的 长 度 : 素 所 指 回 的 用 户 数据 ， 和 否则 返回 NULL 











下 面 回顾 一 下 Nginx 对 于 server_name 主 机 名 通配符 的 支持 规则 。 


. 首先 ， 选 择 所 有 字符 串 完 全 匹配 的 servet_hame， 如 


www.testweb.com 。 
. 其次， 选择 通配符 在 前 面 的 sefvet_hame， 如 #.testweb.com。 
再次， 选择 通配符 在 后 面 的 setvef_hame， 如 www.testweb.#。 


实际 上 ， 上 面 介绍 的 这 个 规则 就 是 Nginx 实 现 的 
ngx_hash_combined_t 通 配 符 散 列表 的 规则 。 下 面 先 来 看 一 下 
ngx_hash_combined_t 的 结构 ， 代 码 如 下 。 








typedef struct { 
// 用 于 精确 匹配 的 基本 散 列 表 


ngx_hash_t hash; 
// 用 于 查询 前 置 通配符 的 散 列 表 


ngx_hash wildcard t *wc_head; 
// 用 于 查询 后 置 通配符 的 散 列 表 


ngx_hash wildcard t *wc_ tail; 
} ngx_hash_combined_t; 





如 图 7-12 所 示 ，ngx_hash_combined_t 是 由 3 个 散 列 表 所 组 成 :第 1 个 
散 列 表 hash 是 普通 的 基本 散 列 表 ， 第 2 个 散 列表 wc_head 所 包含 的 都 是 带 
前 置 通配符 的 元 素 ， 第 3 个 散 列 表 wc_tail 所 包含 的 都 是 带 后 置 通配符 的 
元 并 





ngx_hash _combined _+ 


+hash : ngx_hash_t 





el + wc_head : ngx_hash_wildcard _+ 
一 + wc tail: ngx_hash_wildcard _+ 
全 +ngx_hash_find _combined () 


othe] ee 
、 a 
应 的 结构 体 


完全 匹配 的 散 列 表 





*. test .com 对 记 


的 结构 体 





前 置 通配符 散 列 表 












ww.test.* 对 应 
指针 | 8 |www.test … value | len name 0 
后 置 通配符 散 列 表 


图 7-12 ngx_hash_combined_t 通 配 符 散 列 表 的 结构 示意 


人 @@O i 意 前 置 通配符 散 列 表 中 元 素 的 关键 字 ， 在 把 + 通配符 去 掉 
后 ， 会 按照 “” 符 号 分 隔 ， 并 以 倒序 的 方式 作为 关键 字 来 存储 元 素 。 
相应 的 ， 在 查询 元 素 时 也 是 做 相同 处 理 。 


在 查询 元 素 时 ， 可 以 使 用 ngx_hash_combined_t 提 供 的 方法 
ngx_hash_find_combined， 下 和 面 先 来 看 看 它 的 定义 ( 它 的 参数 、 返 回 值 
含义 与 ngx_hash_find_wc_head 或 者 ngx_hash_find_wc _tail 方 法 相同 〉。 


void *ngx_hash_find_ combined(ngx_hash_ combined t *hash, ngx_uint_t key, u_char *namk 





在 实际 向 ngx_hash_combined_t 通 配 符 散 列表 查询 元 素 时 ， 
ngx_hash_find_combined 方 法 的 活动 图 如 图 7-13 所 示 ， 这 是 有 严格 顺序 
的 ， 即 当 1 个 查询 关键 字 同 时 匹配 3 个 散 列 表 时 ， 一 定 是 返回 普通 的 完全 
匹配 散 列 表 的 相应 元 素 。 









在 hash 完 全 匹配 散 列 表 中 查询 元 素 


[没有 查询 到 ] 


在 wc_head 通 配 符 前 置 散 列表 中 查询 元 素 


圣 查询 到 |] 









在 we_tail 通配符 后 置 散 列表 中 查询 元 素 
[已 经 查询 到 ] 





[未 查询 到 , 返回 NULL] [已 经 查询 到 ] 


图 7-13 ”通配符 散 列 表 ngx_hash_find_combined 方 法 查询 元 素 的 活动 图 


2. 如 何 初 始 化 


上 文中 对 于 普通 的 散 列表 和 通配符 散 列 表 的 原理 和 查询 方法 做 了 详 
细 的 解释 ， 实 际 上 ，Nginx 也 封装 了 完善 的 初始 化 方法 ， 以 用 于 这 些 散 
列表 ， 并 且 Nginx 还 具备 在 初始 化 时 添加 通配符 元 率 的 能 力 。 鉴 于 此 ， 
如 果 功 能 较 多 ， 初 始 化 方法 的 使 用 残 会 有 些 复杂 。 下 面 介 绍 一 下 初始 化 
方法 的 使 用 。 


Nginx 专 门 提供 了 ngx_hash_init_t 结 构 体 用 于 初始 化 散 列 表 ， 代 码 如 
下 。 





typedef struct { 
// 指向 普通 的 完全 匹配 艇 列表 


ngx_hash_t *hash,; 
// 用 于 初始 化 预 添 加 元 素 的 散 列 方法 


ngx_hash_key_pt key; 
// 茹 列表 中 楼 的 最 大 数目 


ngx_uint_t max_size; 
// 散 列表 中 一 个 槽 的 空间 大 小 ， 它 限制 了 每 个 散 列表 元 素 关键 字 的 最 大 长 度 


ngx_uint_t bucket_ size,; 
// 散 列表 的 名 称 


char *name 
/* 内 存 池 ， 它 分 配 散 列 表 (最 多 


3 个 ， 包 括 


1 个 普通 散 列 表 、 


1 个 前 置 通配符 散 列 表 、 


1 个 后 置 通配符 散 列 表 ) 中 的 所 有 模 


4 
ngx_pool_t *pool; 
/* 临 时 内 存 池 ， 它 仅 存 在 于 初始 化 散 列 表 之 前 。 它 主要 用 于 分 配 一 些 临 时 的 动态 数组 ， 带 通配符 的 元 素 在 初 


*/ 
ngx_pool _t *temp_pool; 
} ngx_hash_init_t; 





ngx_hash_init_t 结 构 体 的 用 途 只 在 于 初始 化 散 列 表 ， 到 底 初 始 化 散 
列表 时 会 预 分 配 多 少 个 模 呢 ?这 并 不 完全 由 max_size 成 员 决 定 的 ， 而 是 
由 在 做 初始 化 准备 时 预先 加 入 到 散 列 表 的 所 有 元 素 决 定 的 ， 包 括 这 些 元 
素 的 总 数 、 每 个 元 素 关 键 字 的 长 度 等 ， 还 包括 操作 系统 一 个 页 面 的 大 
小 。 这 个 算法 较 复杂 ， 可 以 在 ngx_hash_init_t 函 数 中 得 到 。 我 们 在 使 用 
它 时 只 需要 了 解 在 初始 化 后 每 个 hgx_hash_t 结 构 体 中 的 size 成 员 不 由 
ngx_hash_init_t 完 全 决定 即 可 。 图 7-14 显 示 了 ngx_hash_init_t 结 构 体 及 其 
支持 的 方法 。 





ngx hash init 


thash 

+key 

tHmax size 

tbucket size 

+name 

+ pool 

ttemp pool 

tngx hash init () 

tngx hash wildcard init () 





图 7-14 ngx_hash_init_t 的 结构 及 其 提供 的 方法 


ngx_hash_init_t 的 这 两 个 方法 负责 将 ngx_hash_keys_arrays_t 中 的 相 
应 元 素 初 始 化 到 散 列 表 中 ， 表 7-10 描 述 了 这 两 个 初始 化 方法 的 用 法 。 


表 7-10 ”ngx_hash_init_t 提 供 的 两 个 初始 化 方法 


执行 意义 

hinit 是 散 列 表 初 始 化 结构 体 的 指针 ;| 初始 化 基本 的 散 列 表 。 返 回 
names 是 数组 的 首 地 址 ， 这 个 数组 中 每 个 元 |NGX OK， 表示 初始 化 成 功 ， 这 
素 以 ngx_hash_key_t 作为 结构 体 ， 它 存储 着 | 时 names 数组 已 经 添加 到 hinit- 
预 洲 加 到 散 列 表 中 的 元 素 ; nelts 是 names 数 | >hash 散 列 表 中 了 ; 返回 NGX_ 
组 的 元 素数 目 ERROR， 表 示 初 始 化 失败 


方法 名 







ngx int tngx hash init 
(ngx_ hash init t *hinit, 
ngx hash key_t *names, 


ngx_ uint t nelts) 


方法 名 
hinit 是 散 列 表 初 始 化 结构 体 的 指针 ;| 初始 化 通配符 散 列 表 (前 
ngx_int tngx_hash_wildcard_init |names 是 数组 的 首 地 址 ， 这 个 数组 中 每 个 元 | 置 或 者 后 置 )。 返 回 NGX _ 





(ngx_hash init t *hinit， 素 以 ngx_hash_key_t 作为 结构 体 ， 它 存储 着 |OK， 表 示 初 始 化 成 功 ， 这 时 
ngx hash key_t *names, 预 添 加 到 散 列 表 中 的 元 素 (这 些 元 素 的 关键 |names 数组 已 经 添加 到 hinit- 
ngx_uint t nelts) 字 要 么 含有 前 置 通配符 ， 要么 全 有 后 置 通 配 | >hash 散 列 表 中 了 ; 返回 NGX_ 


符 ); nelts 是 names 数组 的 元 素数 日 ERROR ， 表 示 初 始 化 失败 





表 7-10 的 两 个 方法 都 用 到 了 ngx_hash_key_t 结 构 ， 下 面 简单 地 介绍 
一 下 它 的 成 员 。 实 际 上 ， 如 果 只 是 使 用 散 列 表 ， 完 全 可 以 不 用 关心 
ngx_hash_key_t 的 结构 ， 但 为 了 更 深入 地 理解 和 应 用 还 是 简要 介绍 一 下 


人 


巴 。 








typedef struct { 
// 元 素 关键 字 


ngx_str_t key; 
// 由 散 列 方法 算出 来 的 关键 码 


ngx_uint_t key_hash 
// 指向 实际 的 用 户 数据 


void *Value 
} ngx_hash_key_t; 





ngx_hash_keys_arrays_t 对 应 的 ngx_hash_add_key 方 法 负责 构造 
ngx_hash_key_t 结 构 。 下 面 来 看 一 下 ngx_hash_keys_arrays_t 结 构 体 ， 它 
不 负责 构造 散 列 表 ， 然 而 它 却 是 使 用 ngx_hash_init 或 者 
ngx_hash_wildcard_init 方 法 的 前 提 条 件 ， 换 人 句 话 说 ， 如 果 先 构造 好 了 
ngx_hash_keys_arrays_t 结 构 体 ， 束 可 以 非常 简单 地 调用 ngx_hash_init 或 
者 ngx_hash_wildcard_init 方 法 来 创建 文 持 通配符 的 散 列 表 了 。 





typedef struct { 
/* 下 面 的 


keys_hasnh.、 


dns_wc_head_hash、 


dns_wc_tail_hash 都 是 简易 散 列 表 ， 而 


hsize 指 明了 散 列表 的 模 个 数 ， 其 简易 散 列 方法 也 需要 对 


hsize 求 余 


4 
ngx_uint_t hsize; 
/* 内 存 池 ， 用 于 分 配 永 久 性 内 存 ， 到 目前 的 


Nginx 版 本 为 止 ， 该 


poo] 成 员 没有 任何 意义 


*/ 
ngx_pool t *pool; 
// 临时 内 存 池 ， 下 面 的 动态 数组 需要 的 内 存 都 由 


temp_poo1 内 存 池 分 配 


ngx_pool t *temp_pool; 
// 用 动态 数组 以 


ngx_hash_key_t 结 构 体 保存 着 不 含有 通配符 关键 字 的 元 素 


ngx_array_t keys; 
/* 一 个 极其 简易 的 散 列 表 ， 它 以 数组 的 形式 保存 着 


hsize 个 元 素 ， 每 个 元 素 都 是 


ngx_array_t 动 态 数 组 。 在 用 户 添加 的 元 素 过 程 中 ， 会 根据 关键 码 将 用 户 的 


ngx_str_t 类 型 的 关键 字 添 加 到 


ngx_array_t 动 态 数 组 中 。 这 里 所 有 的 用 户 元 素 的 关键 字 都 不 可 以 带 通 配 符 ， 表 示 精 确 匹 配 


*/ 
ngx_array_t *keys_hash; 
/* 用 动态 数组 以 


ngx_hash_key_t 结 构 体 保存 着 含有 前 置 通配符 关键 字 的 元 素 生成 的 中 间 关 键 字 


* 
ngx_array_t dns_wc_head ; 
/* 一 个 极其 简易 的 散 列 表 ， 它 以 数组 的 形式 保存 着 





hsize 个 元 素 ， 每 个 元 素 都 是 


ngx_array_t 动 态 数组 。 在 用 户 添 加 元 素 过 程 中 ， 会 根据 关键 码 将 用 户 的 


ngx_Sstr 七 类 型 的 关键 字 添 加 到 


ngx_array tt 动态 数组 中 。 这 里 所 有 的 用 户 元 素 的 关键 字 都 带 前 置 通 配 符 


* 

/ 
ngx_array_t *dns_wc_head_hash,; 
/* 用 动态 数组 以 





ngx_hash_key_t 结 构 体 保存 着 含有 后 置 通配符 关键 字 的 元 素 生成 的 中 间 关 键 字 


*/ 
ngx_array_t dns_wc_ tail; 
/* 一 个 极其 简易 的 散 列 表 ， 它 以 数组 的 形式 保存 着 





hsize 个 元 素 ， 每 个 元 素 都 是 


ngx_array ft 动态 数组 。 在 用 户 添加 元 素 过 程 中 ， 会 根据 关键 码 将 用 户 的 


ngXx_Sstr 七 类 型 的 关键 字 添 加 到 


ngx_array _t 动 态 数 组 中 。 这 里 所 有 的 用 户 元 素 的 关键 字 都 带 后 置 通配符 


*/ 
ngx_array_t *dns_ wc_ tail hash,; 
} ngx_hash_keys_arrays_t,; 











如 图 7-15 所 示 ，ngx_hash_keys_arrays_t 中 的 3 个 动态 数组 容器 keys、 
dns_wc_head、dns_wc_tail 会 以 ngx_hash_key_t 结 构 体 作为 元 素 类 型 ， 分 
别 保存 完全 匹配 关键 字 、 带 前 置 通配符 的 关键 字 、 带 后 置 通配符 的 关键 
字 。 同 时 ，ngx_hash_keys_arrays_t 建 立 了 3 个 简易 的 散 列表 keys_hash、 


dns_wc_head_hash、dns_wc tail hash， 这 3 个 散 列 表 用 于 快速 向 上 述 3 个 
动态 数组 容器 中 插入 元 素 。 


ngx hash key t ngx hash keys arrays _t 


+key 
+key_hash 
+value 


十 dns _we head 
dns_wc head hash 








二 dns_wWc tail 
+dns_wc tail _hash 

/| 1 +ngx_ hash _ keys array _init () 
+ngx hash add key() 


A 水 


www .test.com 关 键 < 


ngx_str t 组 成 的 动态 数组 


1 
ngx str t 组 成 的 动态 数组 


的 动态 数组 在 上 面 3 个 散 列表 中 ， 按 
照 每 个 关键 字 的 散 列 码 指 
定 的 槽 存放 ngx_str_t 组 成 
| 的 动态 数组 ， 每 个 ngx_str_t 
指向 真正 的 关键 字 的 值 







*. test .com 关键 字 











ngx_str_t 组 万 





Www .test.* 关键 字 


在 这 3 个 动态 数组 的 
ngx_hash_key_t 元 素 中 ， 


key FSS valug key 指 向 关键 字 的 值 ， 
hash key_hash 是 计算 出 的 散 列 
一 码 ，value 指 向 实际 的 用 
ngx hash key t 户 数据 


图 7-15 ngx_hash_keys_arrays_t 中 动态 数组 、 散 列表 成 员 的 简易 示意 图 


为 什么 要 设立 这 3 个 简易 散 列 表 呢 ?如 果 没 有 这 3 个 散 列 表 ， 在 癌 
keys、dns_wc_head、dns_wc_tail 动 态 数组 添加 元 素 时 ， 为 了 避免 出 现 相 
同 关 键 字 的 元 素 ， 每 添加 一 个 关键 字 元 素 都 需要 过 有 历 整个 数组 。 有 了 


keys_hash、dns_wc_head_hash、dns_wc tail hash 这 3 个 简易 散 列 表 后 ， 

向 keys、dns_wc_head、dns_wc_tail 动 态 数组 添加 1 个 元 素 时 ， 就 用 这 
个 元 素 的 关键 字 计 算出 散 列 码 ， 然 后 按照 散 列 人 码 在 keys_hash、 
dns_wc_head_hash、dns_wc_tail_hash 散 列表 中 的 相应 位 置 建立 
ngx_array_t 动 态 数 组 ， 动 态 数 组 中 的 每 个 元 素 是 ngx_str_t， 它 指向 关键 
字 字 符 串 。 这 样 ， 再 次 添加 同名 关键 字 时 ， 束 可 以 由 散 列 码 立 刻 获 得 
经 添加 的 关键 字 ， 以 此 来 判定 是 否 合法 或 者 进行 元 素 合 并 操作 。 





ngx_hash_keys_arrays_t 之 所 以 设计 得 比较 复杂 ， 是 为 了 让 keys、 
dns_wc_head、dns_wc tail 这 3 个 动态 数组 中 存放 的 都 是 有 效 的 元 素 。 表 
7-11 介 绍 了 ngx_hash_keys_arrays_t 提 供 的 两 个 方法 。 


表 7-11 ngx_hash_keys_arrays_t 提 供 的 两 个 方法 


执行 意义 
ha 是 要 初始 化 的 ngx_hash_keys_arrays_t| 初始 化 ngx_hash keys arrays { 
ngx_int tngx_hash keys array_init | 结构 体 指 针 ; type 取 值 范围 有 两 个 ， 其 中 | 结构 体 ， 在 向 ha 加 入 成 员 前 必 


方法 名 














(ngx_ hash keys_ arrays_t *ha., NGX _HASH SMALL 表示 待 初 始 化 的 无 | 须 先 调用 该 方法 。 返 回 NGX 
ngx_uint_t type) 素 较 少 ， 而 NGX_HASH LARGE 表示 待 |OK， 表 示 成 功 ， 返 回 NGX_ 


初始 化 的 元 素 较 多 ERROR， 表 示 失 败 
ha 是 要 初始 化 的 ngx_hash keys_arrays 

t 结 构 体 指针 ; key 是 添加 元 素 的 关键 字 ; 

value 是 key 关键 字 对 应 的 用 户 数据 的 指 











ngx int tngx hash add key 针 ; flags 的 取 值 有 3 种 : NGX HASH ; i 
de ee 向 ha 中 添加 1 个 元 素 。 返 
(ngx hash keys arrays_t *ha., WILDCARD KEY 表示 需要 处 理 通 配 符 ; a 
a « 一 ww | 回 NGX_OK， 表 示 成 功 ， 返回 
ngx str t *key. vold *value, NGX HASH READONLY KEY 表示 关键 


NE NGX_ERROR， 表 示 失 败 
ngx_ uint t flags) 字 不 可 以 做 更 改 ( 加 2 


写 关键 字 来 获取 散 列 码 ); 其 他 值 表示 既 不 
处 理 通配符 ， 又 允许 通过 把 关键 字 全 小 写 
来 获取 散 列 码 


ngx_hash_keys_array_init 方 法 的 type 参 数 将 会 决定 


ngx_hash_keys_arrays_t 中 3 个 简易 散 列 表 的 大 小 。 当 type 为 
NGX_HASH_SMALL 时 ， 这 3 个 散 列 表 中 槽 的 数目 为 107 个 ;， 当 type 为 


NGX_HASH_LARGE 时 ， 这 3 个 散 列 表 中 槽 的 数目 为 10007 个 。 


在 使 用 ngx_hash_keys_array_init 初 始 化 ngx_hash_keys_arrays_t 结 构 
体 后 ， 就 可 以 调用 ngx_hash_add_key 方 法 向 其 加 入 散 列 表 元 素 了 。 当 添 
加 元 素 成 功 后 ， 再 调用 ngx_hash_init_t 提 供 的 两 个 初始 化 方法 来 创建 散 
列表 ， 这 样 得 到 的 散 列表 就 是 完全 可 用 的 容器 了 。 


7.7.3” 带 通配符 散 列 表 的 使 用 例子 


散 列 表 元 素 ngx_hash_elt_t 中 value 指 针 指 癌 的 数据 结构 为 下 面 定 义 
的 TestWildcardHash-Node 结 构 体 ， 代 人 码 如 下 。 





typedef struct { 
// 用 于 散 列 表 中 的 关键 字 


ngx_str_t Servername 
// 这 个 成 员 仅 是 为 了 方便 区 别 而 已 


ngx_int_t seq,; 
} TestwildcardHashNode ; 





每 个 散 列 表 元 素 的 关键 字 是 servername 字 符 串 。 下 面 先 定义 
ngx_hash_init_t 和 ngx_hash_keys_arrays_t 变 量 ， 为 初始 化 散 列 表 做 准 
备 ， 代 码 如 下 。 





// 定义 用 于 初始 化 散 列 表 的 结构 体 


ngx_hash_init_t hash 
/* ngx_hash_keys_arrays _ tt 用 于 预先 向 散 列表 中 添加 元 素 ， 这 里 的 元 素 支持 带 通 配 符 





*/ 
ngx_hash_keys_arrays_t ha; 
// 支持 通配符 的 散 列表 





ngx_hash_combined t combinedHash; 
ngx_memzero(&ha, sizeof(ngx_hash_ keys_arrays_t)); 











combinedHash 是 我 们 定义 的 用 于 指 同 散 列 表 的 变量 ， 它 包括 指向 3 
个 散 列 表 的 指针 ， 下 面 会 依次 给 这 3 个 散 列表 指针 赋值 。 





// 临时 内 存 池 只 是 用 于 初始 化 通配符 散 列 表 ， 在 初始 化 完成 后 就 可 以 销毁 掉 


ha.temp_pool = ngx_create pool(16384, cf->10g); 
if (ha.temp_pool == NULL) { 

return NGX_ERROR; 
} 
/由 于 这 个 例子 是 在 
ngx_http_mytest_postconf 遂 数 中 的 ， 所 以 就 用 了 


ngx_conf_t 类 型 的 


Cf 下 的 内 存 池 作为 散 列 表 的 内 存 池 


ha.pool = cf->pool; 





调用 ngx_hash_keys_array_init 方 法 来 初始 化 nha， 为 下 一 步 同 ha 中 加 
入 散 列 表 元 素 做 好 准备 ， 代 码 如 下 。 








if (ngx_hash_keys_array_init(&ha, NGX_HASH_LARGE) != NGX_OK) { 
return NGX_ERROR; 
} 








本 节 按 照 图 7-12 和 图 7-15 中 的 例子 建 并 3 个 数据 ， 并 且 会 窗 新 7.7 节 
中 介绍 的 散 列 表 内 容 。 我 们 建立 的 testHashNode[3] 这 3 个 
TestWildcardHashNode 类 型 的 结构 体 ， 分 别 表 示 可 以 用 前 置 通 配 符 匹配 
的 散 列表 元 素 、 可 以 用 后 置 通配符 匹配 的 散 列 表 元 素 、 需 要 完全 匹配 的 
散 列 表 元 素 。 














TestwildcardHashNode testHashNode[3]; 

testHashNode[0].servername.len = ngx_strlen("*,test,.com"); 
testHashNode[0].servername.data = ngx_pcalloc(cf->pool, ngx_strlen("*.,test.com")); 
ngx_memcpy(testHashNode[0].servername.data,"*.test.com",ngx_strlen("*.test.com")); 
testHashNode[1].servername.len = ngx_strlen("www.test.*"); 
testHashNode[1].servername.data = ngx_pcalloc(cf->pool, ngx_strlen("www.test.*")); 
ngx_memcpy(testHashNode[1].servername.data, "www.test,.*",ngx_strlen("www.test.*")); 
testHashNode[2].servername.len = ngx_strlen("www.test.com"); 
testHashNode[2].servername.data = ngx_pcalloc(cf->pool, ngx_strlen("www.test.com")), 
ngx_memcpy(testHashNode[2].servername.data, "www.test,.com",ngx_strlen("www.test.com". 








下 面 通过 调用 ngx_hash_add_key 方 法 将 testHashNode[3] 这 3 个 成 员 添 
加 到 ha 中 。 





for (i = 0; i < 3; i++) 


{ 
testHashNode[i].seq = i; 
ngx_hash_add_key(&ha, &testHashNode[i].servername, 
&testHashNode[i],NGX_HASH_WILDCARD_KEY); 

} 





注意 ， 在 上 面 添加 散 列 表 元 素 时 ， flag 设 置 为 
NGX_HASH WILDCARD KEY， 这 样 才 会 处 理 带 通配符 的 关键 字 。 


在 调用 ngx_hash_init_t 的 初始 化 函数 前 ， 先 得 设置 好 ngx_hash_init { 
中 的 成 员 ， 如 覃 的 大 小 、 散 列 方 法 等 ， 如 下 所 示 。 





hash,key = ngx_hash_ key_lc; 
hash.max_size = 100 
hash.bucket_size = 48; 

hash.name = "test_server_name_hash",， 
hash.pool = cf->pool; 





ha 的 keys 动 态 数组 中 存放 的 是 再 要 完全 匹配 的 关键 字 ， 如 果 keys 数 
组 不 为 衬 ， 那 么 开始 初始 化 第 1 个 散 列 表 ， 代 码 如 下 。 








if (ha.keys.nelts) { 
* 需 要 显 式 地 把 


ngx_hash_init_t 中 的 


hash 指 针 指 向 


combinedHash 中 的 完全 匹配 散 列 表 


* 
/ 
hash.hash = &combinedHash.hash,; 
// 初始 化 完全 匹配 艇 列表 时 不 会 使 用 到 临时 内 存 池 


hash.temp_pool = NULL 
/* 将 


keys 动 态 数组 直接 传 给 


ngx_hash_init 方 法 即 可 ， 


ngx_hash_init_t 中 的 


hash 指 针 就 是 初始 化 成 功 的 散 列 表 


Wy 
If (ngx_hash_init(&hash, ha.keys.elts, ha.keys.nelts) != NGX_OK) 


return NGX_ERROR ， 





下 面 继续 初始 化 前 置 通配符 散 列 表 ， 代 码 如 下 。 





if (ha.dns_wc_head.neJts) { 
hash.hash = NULL 
// 注意 ， 


ngx_hash_wildcard_init 方 法 需要 使 用 临时 内 存 池 


hash.temp_pool = ha.temp_pool; 

If (ngx_hash wildcard_init(&hash, ha.dns wc_head.elts, 
ha.dns_wc_head.nelts)!= NGX_OK) 

{ 


return NGX_ERROR, 


/* ngx_hash_init_t 中 的 
hash 指 针 是 
ngx_hash_wildcard_init 初 始 化 成 功 的 散 列表 ， 需 要 将 它 赋 到 
combinedHash .wc_head 前 置 通配符 散 列 表 指 针 中 
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} 


combinedHash.wc_head = (ngx_hash wildcard t *) hash.hash,; 





下 面 继续 初始 化 后 置 通配符 散 列 表 ， 代 码 如 下 。 





if (ha.dns wc_ tail.nelts) { 
hash.hash = NULL; 
// 注意 ， 


ngx_hash_wildcard_init 方 法 需要 使 用 临时 内 存 池 


hash,temp_pool = ha.temp_pool; 
If (ngx_hash wildcard_ init(&hash, ha.dns wc_tail.elts, 


ha,dns_wc_tail.nelts)!= NGX_OK) 
return NGX_ERROR 


YE 人 中 的 

hash 指 针 是 

ngx_hash_wildcard_init 初 始 化 成 功 的 散 列表 ， 需 要 将 它 赋 到 
combinedHash .wc_tail 后 置 通配符 散 列 表 指 针 中 


*/ 
combinedHash.wc_tail = (ngx_hash wildcard t *) hash.hash,; 





到 此 ， 临 时 内 存 池 已 经 没有 存在 的 意义 了 ， 也 就 是 说 ， 
ngx_hash_keys_arrays_t 中 的 这 些 数组 、 简 易 散 列表 都 可 以 销毁 了 。 
时 ， 只 需要 简单 地 把 temp_pool 内 存 池 销毁 束 可 以 了 ， 代 码 如 下 。 





ngx_destroy_pool(ha.temp_pool); 








下 面 检查 一 下 散 列 表 是 否 工作 正常 。 首 先 ， 碍 询 关 键 字 
wwwi.test.org， 实 际 上 ， 它 应 该 匹配 后 置 通配符 散 列 表 中 的 元 素 
www .test.*， 代 码 如 下 。 








// 首先 定义 待 查询 的 关键 字 字 符 串 


findServer 

ngx_str_t findServer; 

findServer.len = ngx_strlen("www.test.org"); 

/* 为 什么 必须 要 在 内 存 池 中 分 配 空间 以 保存 关键 字 呢 ?因为 我 们 使 用 的 散 列 方法 是 


ngx_hash_key_lc， 它 会 试 着 把 关键 字 全 


*/ 
findServer.data = ngx_pcalloc(cf->pool, ngx_strlen("www.test.org")); 


ngx_memcpy(findServer .data "www.test.org",ngx_strlen("www.test.org")); 
/* ngx_hash_find_combined 方 法 会 查找 出 


www,test.* 对 应 的 散 列 表 元 素 ， 返 回 其 指向 的 用 户 数据 


ngx_hash_find_combined， 也 就 是 


testHashNode[1]*/ 
TestwildcardHashNode* findHashNode = 
ngx_hash_find_combined(&combinedHash, 
ngx_hash_ key_lc(findServer.data, findServer.1len), 
findServer.data, findServer.1en); 





如 果 没 有 查询 到 的 话 ， 那 么 findHashNode 值 为 NULL 空 指针 。 


下 面试 着 查询 www.testcom， 实 际 上 ，testHashNode[0]、 





testHashNode[1]、testHashNode[2] 这 3 个 节点 都 是 匹配 的 ， 因 为 
*.test.com、Www.test.*、Wwww.test.com 明 显 都 是 匹配 的 。 但 按照 完全 [ 匹 
配 最 优先 的 规则 ，ngx_hash_find_combined 方 法 会 返回 testHashNode[2] 的 
地 址 ， 也 就 是 www.testcom 对 应 的 元 素 。 





findServer.len = ngx_strlen("www.test.com"); 
findServer.data = ngx_pcalloc(cf->pool, ngx_strlen("www.test.com")); 
ngx_memcpy(findServer.data, "www.test.com",ngx_strlen("www.test.com")); 
findHashNode = ngx_hash_find_combined(&combinedHash， 
ngx_hash_key_lc(findServer .data，TfindServer ,Jen)， 
findServer .data，findServer .len)， 





下 面 测试 一 下 后 置 通配符 散 列表 。 如 果 查 询 的 关键 字 
是 “smtp.test.com”， 那 么 查询 到 的 应 该 是 关键 字 为 *.test.com 的 元 素 


testHashNode[0]。 





findServer.len = ngx_strlen("smtp.test.com"); 
findServer.data = ngx_pcalloc(cf->pool, ngx_strlen("smtp.test.com")); 
ngx_memcpy(findServer.data, "smtp.test.com",ngx_strlen("smtp.test.com")); 


findHashNode = ngx_hash_find_combined(&combinedHash， 
ngx_hash_key_lc(findServer .data，TfindServer ,Jen)， 
findServer .data，findServer .len)， 


一 


本 章 介 绍 了 Nginx 的 常用 容器 ， 这 对 我 们 开发 复杂 的 Nginx 模 块 非常 
有 意义 。 当 我 们 需要 用 到 高 级 的 数据 结构 时 ， 选 择 手段 是 非常 少 的 ， 
为 makefile 都 是 由 Nginx 的 configure 脚 本 生成 的 ， 如 果 想 加 入 第 三 方 中 间 
件 将 会 带 来 许多 风险 ， 而 自己 重新 实现 容器 的 代价 又 非常 高 ， 这 时 使 用 
Nginx 提 供 的 通用 容器 就 很 有 意义 了 。 然 而 ，Nginx 封 装 的 这 几 种 容器 在 
使 用 上 各 不 相同 ， 有 些 令 人 头疼 ， 而 且 代码 注释 几乎 没有 ， 就 造成 了 使 
用 这 几 个 容器 很 困难 ， 还 容易 出 错 。 通 过 阅读 本 章 内 容 ， 相 信 读 者 不 再 
会 为 这 些 容器 的 使 用 而 烦恼 了 ， 而 且 也 应 该 具备 轻松 修改 、 升 级 这 些 容 
器 的 能 力 了 。 了 解 本 章 介绍 的 容器 是 今后 深入 开发 Nginx 的 基础 。 
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第 8 章 ”Nginx 基 础 架构 


在 本 书 的 第 二 部 分 ， 我 们 已 经 学 习 了 如 何 开 发 HITP 模 块 ， 这 使 得 
我 们 可 以 实现 高 性 能 、 定 制 化 的 Web 服务 器 功能 。 不 过 ，Nginx 自 身 是 
高 度 模块 化 设计 的 ， 它 给 予 了 每 一 个 基本 的 Nginx 模 块 足够 的 灵活 性 ， 
也 就 是 说 ， 我 们 不 仅仅 能 开发 HTTP 模 块 ， 还 可 以 方便 地 开发 任何 基于 
TCP 的 模块 ， 甚 至 可 以 定义 一 类 新 的 Nginx 模 块 ， 束 像 HTTP 模 块 、mail 
模块 曾经 做 过 的 那样 。 任 何 我 们 能 想到 的 功能 ， 只 要 符合 本 章 中 描述 的 
Nginx 设 计 原 则 ， 都 可 以 以 模块 的 方式 添加 到 Nginx 服 务 中 ， 从 而 提供 强 
大 的 Web 服 务 器 。 








另外 ，Nginx 的 BSD 许 可 证 足够 开放 和 上 自由 ， 因 此 ， 当 Nginx 的 一 些 
通用 功能 与 要 求 不 符合 我 们 的 想象 时 ， 还 可 以 党 试 着 直接 更 改 它 的 官方 
代码 ， 从 而 更 直接 地 达到 业务 要 求 。 同 时 ，Nginx 也 处 于 快速 的 发 展 
中 ， 代 码 中 免不了 会 有 一 些 Bug， 如 果 我 们 对 Nginx 的 架构 有 充分 的 了 
解 ， 也 可 以 积极 地 协助 完善 Nginx 框 架 代码 。 





以 上 这 些 方向 ， 都 需要 我 们 在 整体 上 对 Nginx 的 架构 有 清晰 的 认 
识 。 因 此 ， 本 章 的 写作 目的 只 有 两 个 : 








. 对 Nginx 的 设计 思路 做 一 个 概括 性 的 说 明 ， 帮 助 读者 了 解 Nginx 的 


设计 原则 ( 见 8.1 节 和 8.2 节 ) 。 


` 将 从 具体 的 框架 代码 入 手 ， 讨 论 Nginx 如 何 启 动 、 运 行 和 退出 ， 
这 里 会 涉及 有 具体 实现 细节 ， 如 master 进 程 如 何 管 理 worket 进 程 、 每 个 模 


块 是 如 何 加 载 到 进程 中 的 等 〈 见 8.3 节 ~8.6 节 ) 。 


通过 阅读 本 章 内 容 ， 我 们 将 会 对 Nginx 这 个 Web 服 务 器 有 一 个 全 面 
的 认识 ， 并 对 日 益 增长 的 各 种 Nginx 模 块 与 核心 模块 的 关系 有 一 个 大 概 
的 了 解 。 另 外 ， 本 章 内 容 将 为 下 一 章 《〈 事 件 模块 ) 以 及 后 续 章 节 中 
HTTP 模 块 的 学 习 打下 基础 。 


8.1 Web 服务 器 设计 中 的 关键 约束 


Nginx 是 一 个 功能 堪 比 Apache 的 Web 服 务 器 。 然 而 ， 在 设计 时 ， 为 
了 使 其 能 够 适应 互联 网 用 户 的 高 速 增长 及 其 带 来 的 多 样 化 需求 ， 在 基本 
的 功能 需求 之 外 ， 还 有 许多 设计 约束 。Nginx 作 为 Web 服 务 器 受制 于 
Web 传 输 协 议 目 里 的 约束 ， 为 外 ， 下 面 将 说 明 的 7 个 关注 点 也 是 Nginx 架 
构 设 计 中 的 关键 约束 ， 本 章 会 分 节 简 要 介绍 这 些 概念 。 在 8.2 节 中 ， 我 


们 将 带 着 这 些 问题 再 看 一 下 Nginx 是 如 何 有 效 提升 这 些 关 注 点 属性 的 。 





1. 性 能 


性 能 是 Nginx 的 根本 ， 如 果 性 能 无 法 超越 Apache， 那 么 它 也 就 没有 
存在 的 意义 了 。 这 里 所 说 的 性 能 主体 是 Web 服务器 ， 因 此 ， 人 性 能 这 个 概 
念 主要 是 从 网 络 角度 出 发 的 ， 它 包含 以 下 3 个 概念 。 


(1) 网 络 性 能 


这 里 的 网 络 性 能 不 是 针对 一 个 用 户 而 言 的 ， 而 是 针对 Nginx 服 务 而 
言 的 。 网 络 性 能 是 指 在 不 同 负载 下 ，Web 服 务 在 网 络 通 信 上 的 吞吐 量 。 
而 带宽 这 个 概念 ， 就 是 指 在 特定 的 网 络 连接 上 可 以 达到 的 最 大 吞吐 量 。 
因此 ， 网 络 性 能 肯定 会 受制 于 融 宽 ， 当 然 更 多 的 是 受制 于 Web 服 务 的 软 
件 架 构 。 

















在 大 多 数 场景 下 ， 随 着 服务 器 上 并 发 连接 数 的 增加 ， 网 络 性 能 部会 
有 所 下 降 。 目 前 ， 我 们 在 谈 网 络 性 能 时 ， 更 多 的 是 对 应 于 高 并 发 场景 。 
例如 ， 在 几 万 或 者 几 十 万 并 发 连接 下 ， 要 求 我 们 的 服务 器 仍然 可 以 保持 
较 高 的 网 络 吞 吐 量 ， 而 不 是 当 并 发 连接 数 达 到 一 定数 量 时 ， 服 务 器 的 
CPU 等 资源 大 都 当 费 在 进程 间 切 换 、 休 眠 、 等 待 等 其 他 活动 上 ， 导 致知 
叶 量 大 幅 下 降 。 














(2) 单 次 请 求 的 延迟 性 


单 次 请 求 的 延迟 性 与 上 面 说 的 网 络 性 能 的 差别 很 明显 ， 这 里 只 是 针 
对 一 个 用 户 而 言 的 。 对 于 Web 服 务 器 ， 延 迟 性 就 是 指 服务 器 初次 接收 到 
一 个 用 户 请 求 直至 返回 啊 应 之 间 持 续 的 时 间 。 








服务 器 在 低 并 及 和 凯 并 发 连接 数量 下 ， 单 个 请 求 的 平均 延迟 时 间 肯 
定 是 不 同 的 。Nginx 在 设计 时 更 应 该 考虑 的 是 在 高 并 发 下 如 何 保持 平均 
时 延性 ， 使 其 不 要 上 升 得 太 快 。 











(3) 网 络 效率 


网 络 效率 很 好 理解 ， 惑 是 使 用 网 络 的 效率 。 例 如 ， 使 用 长 连接 
(keepalive) 代 蔡 短 连接 以 减少 建立 、 关 闭 连接 带 来 的 网 络 交 互 ， 使 用 
压缩 算法 来 增加 相同 吞吐 量 下 的 信息 携带 量 ， 使 用 缓存 来 减少 网 络 交 互 
次 数 等 ， 它 们 都 可 以 提高 网 络 效 率 。 


2. 可 伸缩 性 


可 伸缩 性 指 架 构 可 以 通过 添加 组 件 来 提升 服务 ， 或 者 允许 组 件 之 间 
具有 交互 功能 。 一 般 可 以 通过 简化 组 件 、 降 低 组 件 间 的 耦合 度 、 将 服务 
分 散 到 许多 组 件 等 方法 来 改善 可 伸缩 性 。 可 伸缩 性 受到 组 件 间 的 交互 频 
率 ， 以 及 组 件 对 一 个 请 求 是 使 用 同步 还 是 异步 的 方式 来 处 理 等 条 件 制 
约 。 





3. 简 单 性 

简单 性 通常 指 组 件 的 简单 程度 ， 每 个 组 件 越 简单 ， 束 会 越 容 易 理 解 
和 实现 ， 也 就 越 容易 被 验证 〈 被 测试 ) 。 一 般 ， 我 们 通过 分 离 关 注 点 原 
则 来 设计 组 件 ， 对 于 整体 架构 来 襄 ， 通 党 使 用 通用 性 原则 ， 统 一 组 件 的 
接口 ， 这 样 就 减少 了 架构 中 的 变数 。 


4. 可 修改 性 





简单 来 讲 ， 可 修改 性 就 是 在 当前 架构 下 对 于 系统 功能 做 出 修改 的 难 
易 程 度 ， 对 于 Web 服 务 右 来 说 ， 它 还 包括 动态 的 可 修改 性 ， 也 就 是 部 著 
好 Web 服 务 吕 后 可 以 在 不 停止 、 不 重 局 服务 的 前 担 下 ， 提 供给 用 户 不 同 
的 、 符 合 需求 的 功能 。 可 修改 性 可 以 进一步 分 解 为 可 进化 性 、 可 扩展 
性 、 可 定制 性 、 可 配置 性 和 可 重用 性 ， 下 面 简单 说 明 一 下 这 些 概念 。 





(1) 可 进化 性 


可 进化 性 表示 我 们 在 修改 一 个 组 件 时 ， 对 其 他 组 件 产生 负面 影响 的 
程度 。 当 然 ， 每 个 组 件 的 可 进化 性 都 是 不 同 的 ， 越 是 核心 的 组 件 其 可 进 
化 性 可 能 会 越 低 ， 也 就 是 说 ， 对 这 个 组 件 的 功能 做 出 修改 时 可 能 同时 必 
须 修改 其 他 大 量 的 相关 组 件 。 








对 于 Web 服 务 需 来 说 ,“ 进 化 "这 个 概念 按照 服务 是 否 在 运行 中 又 可 
以 分 为 静态 进化 和 动态 进化 。 优 秀 的 静态 进化 主要 依赖 于 架构 的 设计 是 
否 足 够 抽象 ， 而 动态 进化 则 不 然 ， 它 与 整个 服务 的 设计 都 是 相关 的 。 


(2) 可 扩展 性 


可 扩展 性 表示 将 一 个 新 的 功能 添加 到 系统 中 的 能 力 〈 不 影响 其 他 功 
能 ) 。 与 可 进化 性 一 样 ， 除 了 静态 可 扩展 性 外 ， 还 有 动态 可 扩展 性 (如 
果 已 经 部 羞 的 服务 在 不 停止 、 不 重 局 情况 下 添加 新 的 功能 ， 就 称 为 动态 
可 扩展 性 ) 。 











(3) 可 定制 性 


可 定制 性 是 指 可 以 临时 性 地 重新 规定 一 个 组 件 或 其 他 架构 元 系 的 特 
性 ， 从 而 提供 一 种 非常 规 服 务 的 能 力 。 如 果 某 一 个 组 件 是 可 定制 的 ， 那 
么 是 指 用 户 能 够 扩展 该 组 件 的 服务 ， 而 不 会 对 其 他 客户 产生 影响 。 文 持 
可 定制 性 的 风格 一 般 会 提高 简单 性 和 可 扩展 性 ， 因 为 通常 情况 下 只 会 实 





现 最 常用 的 功能 ， 不 太 第 用 的 功能 则 交 由 用 户 重 新 定制 使 用 ， 这 样 组 件 
的 复杂 性 就 降低 了 ， 整 个 服务 也 会 更 容易 扩展 。 


(4) 可 配置 性 


可 配置 性 是 指 在 Web 服务 部 着 后 ， 通 过 对 服务 提供 的 配置 文件 进行 
修改 ， 来 提供 不 同 的 功能 。 它 与 可 扩展 性 、 可 重用 性 相关 。 


(5) 可 重用 性 


可 重用 性 指 的 是 一 个 应 用 中 的 功能 组 件 在 不 被 修改 的 情况 下 ， 可 以 
在 其 他 应 用 中 重用 的 程度 。 


5. 可 见 性 








在 Web 服 务 器 这 个 应 用 场景 中 ， 可 见 性 通常 是 指 一 些 关 键 组 件 的 运 
行情 况 可 以 被 监控 的 程度 。 例 如 ， 服 务 中 正在 交互 的 网 络 连接 数 、 绥 存 
的 使 用 情况 等 。 通 过 这 种 监控 ， 可 以 改善 服务 的 性 能 ， 尤 其 是 可 靠 性 。 


6. 可 移植 性 


可 移植 性 是 指 服务 可 以 跨 平 台 运 行 ， 这 也 是 当下 Nginx 被 大 规模 使 
用 的 必要 条 件 。 


7. 可 靠 性 


可 靠 性 可 以 看 做 是 在 服务 出 现 部 分 故障 时 ， 一 个 架构 容易 受到 系统 
层面 故障 影响 的 程度 。 可 以 通过 以 下 方法 提高 可 靠 性 : 避免 单 点 故障 、 
增加 元 余 、 人 允许 监视 ， 以 及 用 可 恢复 的 动作 来 缩小 故障 的 范围 。 





8.2 Nginx 的 架构 设计 


8.1 市 列 出 了 进行 Nginx 设 计时 需要 格外 重视 的 7 个 关键 点 ， 本 市 将 
介绍 Nginx 是 如 何在 这 7 个 关键 点 上 提升 Nginx 能 力 的 。 


8.2.1 ”优秀 的 模块 化 设计 


高 度 模块 化 的 设计 是 Nginx 的 架构 基础 。 在 Nginx 中 ， 除 了 少量 的 核 
心 代码 ， 其 他 一 切 省 为 模块 。 这 种 模块 化 设计 同时 具有 以 下 儿 个 特点 : 








(1) 高 度 抽象 的 模块 接口 


所 有 的 模块 都 遵循 着 同样 的 ngx_module_t 接 口 设计 规范 ， 这 减少 了 
整个 系统 中 的 变数 ， 对 于 8.1 节 中 列 出 的 关键 关注 点 ， 这 种 方式 带 来 了 
展 好 的 简单 性 、 静 态 可 扩展 性 、 可 重用 性 。 











(2) 模块 接口 非常 简单 ， 具 有 很 高 的 灵活 性 


模块 的 基本 接口 ngx_module _{t 足 够 简单 ， 只 涉及 模块 的 初始 化 、 退 
出 以 及 对 配置 项 的 处 理 ， 这 同时 也 带 来 了 足够 的 灵活 性 ， 使 得 Nginx 比 
较 简 单 地 实现 了 动态 可 修改 性 《参见 8.5 节 和 8.6 节 ， 可 知 如 何 通 过 HUP 
童 号 在 服务 正常 运行 时 使 新 的 配置 文件 生效 ， 以 及 通过 USR2 信 和 号 实现 
平滑 升级 ) ， 也 就 是 保持 服务 正常 运行 下 使 系统 功能 发 生 改 变 。 





如 图 8-1 所 示 ，ngx_module_t 结 构 体 作为 所 有 模块 的 通用 接口 ， 它 只 
定义 了 init_master、init_ module、init_process、init_thread、exit_thread、 
exit_process、exit_master 这 7 个 回调 方法 (事实 上 ，init_master、 
init thread、exit_thread 这 3 个 方法 目前 都 没有 使 用 ) ， 它 们 负责 模块 的 
初始 化 和 退出 ， 同 时 它们 的 权限 也 非常 高 ， 可 以 处 理 系统 的 核心 结构 体 
ngx_cycle t。 在 8.4 节 ~8.6 节 中 ， 可 以 看 到 以 上 7 个 回调 方法 何 时 会 被 调 
用 。 而 ngx_command_t 类 型 的 commands 数 组 则 指定 了 模块 处 理 配 置 项 的 
方法 ( 详 见 第 4 章 )。 





除了 简单 、 基 础 的 接口 ，ngx_module_t 中 的 ctx 成 员 还 是 一 个 void* 
指针 ， 它 可 以 指向 任何 数据 ， 这 给 模块 提供 了 很 大 的 灵活 性 ， 使 得 下 面 
将 要 介绍 的 多 层次 、 多 类 型 的 模块 设计 成 为 可 能 。ctx 成 员 一 般 用 于 表 
示 在 不 同类 型 的 模块 中 一 种 类 型 模块 所 具备 的 通用 性 接口 。 





(3) 配置 模块 的 设计 


可 以 注意 到 ，ngx_module_t 接 口 有 一 个 type 成 员 ， 它 指明 了 Nginx 允 
许 在 设计 模块 时 定义 模块 类 型 这 个 概念 ， 人 允许 专注 于 不 同 领域 的 模块 按 
照 类 型 来 区 别 。 而 配置 类 型 模块 是 唯一 一 种 只 有 1 个 模块 的 模块 类 型 。 
配置 模块 的 类 型 叫做 NGX_CONF_MODULE， 它 仅 有 的 模块 叫做 
ngx_conf_module， 这 是 Nginx 最 底层 的 模块 ， 它 指导 着 所 有 模块 以 配置 
项 为 核心 来 提供 功能 。 因 此 ， 它 是 其 他 所 有 模块 的 基础 。 配 置 模块 使 
Nginx 提 供 了 高 可 配置 性 、 高 可 扩展 性 、 高 可 定制 性 、 高 可 伸缩 性 。 
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图 8-1 ngx_module_t 接 口 及 其 对 核心 、 事 件 、HTTP、mail 等 4 类 模块 ctx 
上 下 文成 员 的 具体 化 


(4) 核心 模块 接口 的 简单 化 


Nginx 还 定义 了 一 种 基础 类 型 的 模块 : 核心 模块 ， 它 的 模块 类 型 叫 
做 NGX_CORE_ MODULE。 目前 官方 的 核心 类 型 模块 中 共有 6 个 具体 模 








块 ， 分 别 是 ngx_core_module、ngx_errlog_ module、ngx_events_module、 
ngX_openssl_ module、ngx_http_module、ngx_mail_module 模 块 。 为 什么 
要 定义 核心 模块 呢 ? 因为 这 样 可 以 简化 Nginx 的 设计 ， 使 得 非 模 块 化 的 
框架 代码 只 关注 于 如 何 调用 6 个 核心 模块 《大 部 分 Nginx 模 块 都 是 非 核心 
模块 ) 。 


核心 模块 的 接口 非常 简单 ， 如 图 8-1 所 示 ， 它 将 ctx 上 下 文 进一步 实 
例 化 为 ngx_core_module_t 结 构 体 ， 代 人 码 如 下 。 





typedef struct { 
// 核心 模块 名 称 


ngx_str_t name 
// 解析 配置 项 前 ， 


Nginx 框 架 会 调用 


create_conf 方 法 


void *(*create conf)(ngx_cycle t *cycle); 
// 解析 配置 项 完成 后 ， 


Nginx 框 架 会 调用 


init_conf 方 法 


char *(*init conf)(ngx_cycle t *cycle, void *conf ) ， 
} ngx_core module _t; 





ngx_core_module t 上 下 文 是 以 配置 项 的 解析 作为 基础 的 ， 它 提供 了 
create_conf 回 调 方法 来 创建 存储 配置 项 的 数据 结构 ， 在 读 取 nginx.conf 配 








置 文件 时 ， 会 根据 模块 中 的 ngx_command_t 把 解析 出 的 配置 项 存放 在 这 
个 数据 结构 中 ; 它 还 提供 了 init_conf 回 调 方法 ， 用 于 在 解析 完 配 置 文件 
后 ， 使 用 解析 出 的 配置 项 初始 化 核心 模块 功能 。 除 此 以 外 ，Nginx 框 架 
不 会 约束 核心 模块 的 接口 、 功 能 ， 这 种 简洁 、 灵 活 的 设计 为 Nginx 实 现 
动态 可 配置 性 、 动 态 可 扩展 性 、 动 态 可 定制 性 带 来 了 极 大 的 便利 ， 这 

样 ， 在 每 个 模块 的 功能 实现 中 就 会 较 少 地 考虑 如 何不 停止 服务 、 不 重 局 
服务 来 实现 以 上 功能 。 


这 种 设计 也 使 得 每 一 个 核心 模块 都 可 以 自由 地 定义 全 新 的 模块 类 
型 。 因 此 ， 作 为 核心 模块 ，ngx_events_module 定 义 了 
NGX_EVENT_MODULE 模 块 类 型 ， 所 有 事件 类 型 的 模块 都 由 
ngx_events_module 核 心 模 块 管理 ，ngx_http_module 定 义 了 
NGX_HTTP_MODULE 模 块 类 型 ， 所 有 HTTP 类 型 的 模块 都 由 
ngx_http_module 核 心 模块 管理 ， 而 ngx_mail_module 定 义 了 
NGX_MAIL_MODULE 模 块 类 型 ， 所 有 MAIL 类 型 的 模块 则 都 由 


ngx_mail_module 核 心 模块 管理 。 
(5) 多 层次 、 多 类 别 的 模块 设计 


所 有 的 模块 间 是 分 层次 、 分 类 别 的 ， 官 方 Nginx 共 有 五 大 类 型 的 模 
块 : 核心 模块 、 配 置 模块 、 事 件 模 块 、HTTP 模 块 、mail 模 块 。 虽然 它 
们 都 具备 相同 的 ngx_module_t 接 口 ， 但 在 请 求 处 理 流程 中 的 层次 并 不 相 
同 。 就 如 同上 面 介绍 过 的 核心 模块 一 样 ， 事 件 模 块 、HTTP 模 块 、mail 





模块 都 会 再 次 具体 化 ngx_module t 接 口 “由 于 配置 类 型 的 模块 只 拥有 1 
个 模块 ， 所 以 没有 具体 化 ctxk 上 下 文成 员 ) ， 如 图 8-2 所 示 。 





图 8-2 展 示 了 Nginx 和 常用 模块 间 的 关系 。 配 置 模块 和 核心 模块 这 两 种 
模块 类 型 是 由 Nginx 的 框架 代码 所 定义 的 ， 这 里 的 配置 模块 是 所 有 模块 
的 基础 ， 它 实现 了 最 基本 的 配置 项 解析 功能 《就 是 解析 nginx.conf 文 
件 ) 。Nginx 框 染 还 会 调用 核心 模块 ， 但 是 其 他 3 种 模块 都 不 会 与 框架 产 
生 直 接 关 系 。 事 件 模块 、HITP 模 块 、mail 模 块 这 3 种 模块 的 共性 是 : 实 
际 上 它们 在 核心 模块 中 各 有 1 个 模块 作为 自己 的 “代言 人 ”， 并 在 同类 模 
块 中 有 1 个 作为 核心 业务 与 管理 功能 的 模块 。 例 如 ， 事 件 模块 是 由 它 
的 “代言 人 ”一 一 ngx_events_module 核 心 模块 定义 ， 所 有 事件 模块 的 加 载 
操作 不 是 由 Nginx 框 架 完成 的 ， 而 是 由 ngx_event_core_module 模 块 负责 
的 。 同 样 ，HTTP 模 块 是 由 它 的 “代言 人 >” 
定义 的 ， 与 事件 模块 不 同 的 是 ， 这 个 核心 模块 还 会 负责 加 载 所 有 的 
HTTP 模 块 ， 但 业务 的 核心 逻辑 以 及 对 于 具体 的 请 求 该 选用 哪 一 个 HTTP 
模块 处 理 这 样 的 工作 ， 则 是 由 ngx_http_core_module 模 块 决定 的 。 至 于 
mail 模 块 ， 因 与 HTTP 模 块 基本 相似 ， 不 再 玖 述 。 
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图 8-2 Nginx 常 用 模块 及 其 之 间 的 关系 


在 这 5 种 模块 中 ， 配 置 模块 与 核心 模块 都 是 与 Nginx 框 架 密切 相关 
的 ， 是 其 他 模块 的 基础 。 而 事件 模块 则 是 HTTP 模 块 和 mail 模 块 的 基 
础 ， 原 因 参 见 8.2.2 节 。HTTP 模 块 和 mail 模 块 的 “地 位 ”相似 ， 它 们 都 更 关 


注 于 应 用 层面 。 在 事件 模块 中 ，ngx_event_core_module 事 件 模块 是 其 他 
所 有 事件 模块 的 基础 ， 在 HTTP 模 块 中 ，ngx_http_core_module 模 块 是 其 
他 所 有 HTTP 模 块 的 基础 ， 在 mail 模 块 中 ，ngx_mail_core_module 模 块 是 
其 他 所 有 mail 模 块 的 基础 。 


8.2.2 ”事件 驱动 架构 








所 谓 事件 驱动 如 构 ， 简 单 来 说 ， 束 是 由 一 些 事件 发 生源 来 产生 事 
件 ， 由 一 个 或 者 多 个 事件 收集 局 来 收集 、 分 发 事件 ， 然 后 许多 事件 处 理 
融会 注册 目 己 感 兴趣 的 事件 ， 同 时 会 “消费 ”这 些 事件 。 


对 于 Nginx 这 个 Web 服 务 嚣 而 言 ， 一 般 会 由 网 卡 、 磁 盘 产 生 事 件 ， 
而 8.2.1 节 中 提 到 的 事件 模块 将 负责 事件 的 收集 、 分 发 操作 ， 而 所 有 的 模 
块 都 可 能 是 事件 消费 者 ， 它 们 首先 需要 疝 事件 模块 注册 感 兴 趣 的 事件 类 
型 ， 这 样 ， 在 有 事件 产生 时 ， 事 件 模 块 会 把 事件 分 友 到 相应 的 模块 中 进 
行 处 理 。 





Nginx 采 用 完全 的 事件 驱动 架构 来 处 理 业务 ， 这 与 传统 的 Web 服 务 
器 〈 如 Apache) 是 不 同 的 。 对 于 传统 Web 服 务 器 而 言 ， 采 用 的 所 谓 事件 
驱动 往往 局 限 在 TCP 连 接 建 立 、 关 闭 事件 上 ， 一 个 连接 建立 以 后 ， 在 其 
关闭 之 前 的 所 有 操作 都 不 再 是 事件 驱动 ， 这 时 会 退化 成 按 序 执行 每 个 操 
作 的 批 处 理 模式 ， 这 样 每 个 请 求 在 连接 建立 后 都 将 始终 占用 着 系统 资 











源 ， 直 到 连接 关闭 才 会 释放 资源 。 要 知道 ， 这 段 时 间 可 能 会 非常 长 ， 从 
1 毫秒 到 1 分 钟 都 有 可 能 ， 而 且 这 段 时 间 内 占用 着 内 存 、CPU 等 资源 也 许 
并 没有 意义 ， 整 个 事件 消费 进程 只 是 在 等 竺 菜 个 条 件 而 已 ， 造 成 了 服务 
铝 资 源 的 极 大 浪费 ， 影 响 了 系统 可 以 处 理 的 并 发 连接 数 。 如 图 8-3 所 
示 ， 这 种 传统 Web 服 务 咒 往往 把 一 个 进程 或 线程 作为 事件 消费 者 ， 当 一 
个 请 求 产 生 的 事件 被 该 进程 处 理 时 ， 直 到 这 个 请 求 处 理 结 束 时 进程 资源 
都 将 被 这 一 个 请 求 所 占用 。 














图 8-3 ”传统 Web 服 务 器 处 理事 件 的 简单 模型 (椭圆 代表 数据 结构 ， 适 形 
代表 进程 ) 


Nginx 则 不 然 ， 它 不 会 使 用 进程 或 线程 来 作为 事件 消费 者 ， 所 谓 的 
事件 消费 者 只 能 是 茶 个 模块 〈 在 这 里 没有 进程 的 概念 ) 。 只 有 事件 收 








集 、 分 发 器 才 有 资格 占用 进程 资源 ， 它 们 会 在 分 发 某 个 事件 时 调用 事件 
消费 模块 使 用 当前 占用 的 进程 资源 ， 如 图 8-4 所 示 。 





图 8-4 中 列 出 了 5 个 不 同 的 事件 ， 在 事件 收集 、 分 发 者 进程 的 一 次 处 
理 过 程 中 ， 这 5 个 事件 按照 顺序 被 收集 后 ， 将 开始 使 用 当前 进程 分 发 事 
件 ， 从 而 调用 相应 的 事件 消费 者 模块 来 处 理事 件 。 当 然 ， 这 种 分 及 、 调 
用 也 是 有 序 的 。 





从 上 面 的 内 容 可 以 看 出 传统 Web 服 务 器 与 Nginx 间 的 重要 差别 : 前 
者 是 每 个 事件 消费 者 独占 一 个 进程 资源 ， 后 者 的 事件 消费 者 只 是 被 事件 
分 发 者 进程 短期 调用 而 已 。 这 种 设计 使 得 网 络 性 能 、 用 户 感知 的 请 求 时 
延 ( 延 时 性 ) 都 得 到 了 提升 ， 每 个 用 户 的 请 求 所 产生 的 事件 会 及 时 虽 
应 ， 整 个 服务 器 的 网 络 否 吐 量 部 会 由 于 事件 的 及 时 啊 应 而 增 大 。 但 这 也 
会 带 来 一 个 重要 的 疾 端 ， 即 每 个 事件 消费 者 者 不 能 有 阻 突 行 为 ， 否 则 将 
会 由 于 长 时 间 占 用 事件 分 发 者 进程 而 导致 其 他 事件 得 不 到 及 时 啊 应 。 尤 
其 是 每 个 事件 消费 者 不 可 以 让 进程 转变 为 休眠 状态 或 等 待 状态 ， 如 在 等 
竺 一 个 信号 量 条 件 的 满足 时 会 使 进程 进入 休眠 状态 。 这 加 大 了 事件 消费 
程序 的 开发 者 的 编程 难度 ， 因 此 ， 这 也 导致 Nginx 的 模块 开发 相对 于 
Apache 来 说 复杂 不 少 〈《 上 文 已 经 提 到 过 ) 。 
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图 8-4 Nginx 处 理事 件 的 简单 模型 


8.2.3 请求 的 多 阶段 异步 处 理 


这 里 所 讲 的 多 阶段 异步 处 理 请 求 与 事件 驱动 架构 是 密切 相关 的 ， 换 
句 话 说 ， 请 求 的 多 阶段 异步 处 理 只 能 基于 事件 驱动 架构 实现 。 什 么 意思 
呢 ? 就 是 把 一 个 请 求 的 处 理 过 程 按 照 事 件 的 触发 方式 划分 为 多 个 阶段 ， 
每 个 阶段 都 可 以 由 事件 收集 、 分 友 絮 来 触 友 。 








例如 ， 处 理 一 个 获取 静态 文件 的 HTTP 请 求 可 以 分 为 以 下 几 个 阶段 


( 见 表 8-1) 。 


表 8-1 ”处理 获取 静态 文件 的 HTTP 请 求 时 切 分 的 阶段 及 各 阶段 的 触发 事 
件 


阶段 意义 触发 事件 
建立 TCP 连接 接收 到 TCP 中 的 SYN 包 
开始 接收 用 户 请 求 接收 到 TCP 中 的 ACK 包 表 示 连 接 建 立成 功 
接收 到 用 户 请 求 并 分 析 已 接收 的 请 求 是 否 完整 接收 到 用 户 的 数据 包 
接收 到 完整 的 用 户 请 求 后 开始 处 理 用 户 请 求 接收 到 用 户 的 数据 包 
由 目标 静态 文件 中 读 取 部 分 内 容 (避免 长 期 阻塞 事 | 接收 到 用 户 的 数据 包 ; 或 者 接收 到 TCP 中 的 ACK 包 表 示 
件 分 发 者 进程 ) 并 直接 发 送 给 用 户 用 户 已 接收 到 上 次 发 送 的 数据 包 ，TCP 滑动 窗口 向 前 滑动 


阶段 意义 
对 于 非 keep-alive 请 求 ， 在 发 送 完 静态 文件 后 主动 
关闭 连接 
由 于 用 户 关闭 连接 而 结束 请 求 


触发 事件 
接收 到 TCP 中 的 ACK 包 表 示 用 户 已 接收 到 之 前 发 送 的 所 
有 数据 包 
接收 到 TCP 中 的 FN 包 





这 个 例子 中 大 致 分 为 7 个 阶段 ， 这 些 阶段 是 可 以 重复 发 生 的 ， 因 
此 ， 一 个 下 载 静 态 资源 请 求 可 能 会 由 于 请 求 数据 过 大 、 网 速 不 稳定 等 因 
素 而 被 分 解 为 成 百 上 二 个 表 8-1 中 所 列 出 的 阶段 。 


异步 处 理 和 多 阶段 是 相辅相成 的 ， 只 有 把 请 求 分 为 多 个 阶段 ， 才 有 
所 谓 的 异步 处 理 。 也 就 是 说 ， 当 一 个 事件 被 分 友 到 事件 消费 者 中 进行 处 
理 时 ， 事 件 消费 者 处 理 完 这 个 事件 只 相当 于 处 理 完 1 个 请 求 的 菏 个 阶 
段 。 什 么 时 候 可 以 处 理 下 一 个 阶段 呢 ? 这 只 能 等 竺 内核 的 通知 ， 即 当下 
一 次 事件 出 现时 ，epoll 等 事件 分 发 器 将 会 获取 到 通知 ， 再 继续 调用 事件 
消费 者 处 理 请 求 。 这 样 ， 每 个 阶段 中 的 事件 消费 者 都 不 清楚 本 次 完整 的 
操作 完 竟 什么 时 候 会 完成 ， 只 能 弄 步 被 动 地 等 竺 下 一 次 事件 的 通知 。 














请 求 的 多 阶段 寞 步 处 理 优势 在 哪里 ? 这 种 设计 配合 事件 驱动 架构 ， 
将 会 极 大 地 提高 网 络 性 能 ， 同 时 使 得 每 个 进程 都 能 全 力 运转 ， 不 会 或 者 
尽量 少 地 出 现 进程 休眠 状况 。 因 为 一 旦 出 现 进程 休眠 ， 必 然 减少 并 发 处 
理事 件 的 数目 ， 一 定 会 降低 网 络 性 能 ， 同 时 会 增加 请 求 处 理 时 间 的 平均 
时 延 ! 这 时 ， 如 果 网 络 性 能 无 法 满足 业务 需求 将 只 能 增加 进程 数目 ， 进 
程 数目 过 多 就 会 增加 操作 系统 内 核 的 额外 操作 : 进程 间 切 换 ， 可 是 频繁 
地 进行 进程 间 切 换 仍 会 消耗 CPU 等 资源 ， 从 而 降低 网 络 性 能 。 同 时 ， 休 
眠 的 进程 会 使 进程 占用 的 内 存 得 不 到 有 效 释 放 ， 这 最 终 必 然 导致 系统 可 
用 内 存 的 下 降 ， 从 而 影响 系统 能 够 处 理 的 最 大 并 发 连接 数 。 














根据 什么 原则 来 划分 请 求 的 阶段 呢 ? 一 般 是 找到 请 求 处 理 流程 中 的 
阻塞 方法 《或 者 造成 阻塞 的 代码 段 } ， 在 阻塞 代码 段 上 按照 下 面 4 种 方 
式 来 划分 阶段 : 


(1) 将 阻 赛 进 程 的 方法 按照 相关 的 触发 事件 分 解 为 两 个 阶段 


一 个 本 身 可 能 导致 进程 休眠 的 方法 或 系统 调用 ， 一 般 都 能 够 分 解 为 
多 个 更 小 的 方法 或 者 系统 调用 ， 这 些 调用 间 可 以 通过 事件 触发 关联 起 
来 。 大 部 分 情况 下 ， 一 个 阻 暑 进程 的 方法 调用 时 可 以 划分 为 两 个 阶段 : 
阻 竖 方 法 改 为 非 阻塞 方法 调用 ， 这 个 调用 非 阻 竖 方法 并 将 进程 归还 给 事 
件 分 有 器 的 阶段 融 是 第 一 阶段 ;增加 新 的 处 理 阶段 〈 第 二 阶段 ) 用 于 处 
理 非 阻塞 方法 最 终 返 回 的 结 采 ， 这 里 的 结果 返回 事件 就 是 第 二 阶段 的 触 
发 事件 。 











例如 ， 在 使 用 send 调 用 发 送 数据 给 用 户 时 ， 如 果 使 用 阻塞 socket 句 
顶 ， 那 么 send 调 用 在 向 操作 系统 内 核 友 出 数据 包 后 就 必须 把 当前 进程 休 
眠 ， 直 到 成 功 发 出 数据 才能 “ 醒 来 ”。 这 时 的 send 调 用 发 送 数据 并 等 待 结 
条 。 我 们 需要 把 send 调 用 分 解 为 两 个 阶段 : 发 送 且 不 等 待 结果 阶段 、 
send 结 果 返 回 阶段 。 因 此 ， 可 以 使 用 非 阻塞 socket 铅 柄 ， 这 样 调用 send 
发 送 数据 后 ， 进 程 是 不 会 进入 休 虐 的 ， 这 就 是 发 送 且 不 等 竺 结果 阶段 ; 
再 把 socket 句 柄 加 入 到 事件 收集 器 中 就 可 以 等 待 相应 的 事件 触及 下 一 个 
阶段 ，send 发 送 的 数据 修 对 方 收 到 后 这 个 事件 整 会 触 太 send 结 果 返 回 阶 
段 。 这 个 send 调 用 就 是 请 求 的 划分 阶段 点 。 


(2) 将 阻塞 方法 调用 按照 时 间 分 解 为 多 个 阶段 的 方法 调用 


注意 ， 系 统 中 的 事件 收集 、 分 发 者 并 非 可 以 处 理 任何 事件 。 如 果 按 
照 前 一 种 方式 试图 划分 杂 个 方法 时 ， 那 么 可 能 会 发 现 找 出 的 触 友 事 件 不 
能 够 被 事件 收集 、 分 发 器 所 处 理 ， 这 时 只 能 按照 执行 时 间 来 拆 分 这 个 方 
法 了 。 





例如 读 取 文件 的 调用 《〈 非 异步 JO) ， 如 果 我 们 读 取 10MB 的 文件 ， 
这 些 文件 在 磁盘 中 的 块 未 必 是 连续 的 ， 这 意味 着 当 这 10MB 文 件 内 容 不 
在 操作 系统 的 缓存 中 时 ， 可 能 需要 多 次 驱动 便 盘 寻 址 。 在 寻 址 过 程 中 ， 
进程 多 半 会 休眠 或 者 等 待 。 我 们 可 能 会 希望 像 上 文 所 说 的 那样 把 读 取 文 
件 调用 分 解 成 两 个 阶段 : 发送 读 取 命 令 且 不 等待 结 果 阶段 、 读 取 结 
回 阶 段 。 这 样 当然 很 好 ， 可 惜 的 是 ， 如 果 我 们 的 事件 收集 、 分 发 者 不 文 











持 这 么 做 ， 该 怎么 办 ? 例如 ， 在 Linux 上 Nginx 的 事件 模块 在 没 打 开 异 步 
IO 时 就 不 支持 这 种 方法 ， 像 ngx_epoll_ module 模 块 主要 是 针对 网 络 事件 
的 ， 而 主机 的 磁盘 事件 目前 还 不 支持 《必须 通过 内 核 异 步 JO) 。 这 
时 ， 我 们 可 以 这 样 来 分 解读 取 文 件 调用 : 把 10MB 均 分 成 1000 份 ， 每 次 
只 读 取 10KB。 这 样 ， 读 取 10KB 的 时 间 就 是 可 控 的 ， 意 味 着 这 个 事件 接 
收 器 占用 进程 的 时 间 不 会 太 久 ， 整 个 系统 可 以 及 时 地 处 理 其 他 请 求 。 








那么 ， 在 读 取 0KB~10KB 的 阶段 完成 后 ， 怎 样 进 入 10KB~20KB 阶 段 
呢 ? 这 有 很 多 种 方式 ， 如 读 取 完 10KB 文 件 后 ， 可 能 需要 使 用 网 络 来 发 
送 它们 ， 这 时 可 以 由 网 络 事件 来 触发 。 或 者 ， 如 果 没 有 网 络 事件 ， 也 可 
以 设置 一 个 简单 的 定时 器 ， 在 某 个 时 间 点 后 再 次 调用 下 一 个 阶段 。 





(3) 在 “无 所 事 事 ” 且 必须 等 竺 系统 的 啊 应 ， 从 而 导致 进程 空转 
时 ， 使 用 定时 融 划 分 阶段 


有 时 阻 窗 的 代码 段 可 能 是 这 样 的 ;进行 某 个 无 阻 窗 的 系统 调用 后 ， 
必须 通过 持续 的 检查 标志 位 来 确定 是 否 继续 癌 下 执行 ， 当 标志 位 没有 获 
得 满足 时 就 人 循环 地 检查 下 去 。 这 样 的 代码 段 本 里 没 有 阻 紧 方法 调用 ， 可 
实际 上 是 阻塞 进程 的 。 这 时 ， 应 该 使 用 定时 喜来 代 蔡 循环 检查 标志 ， 这 
样 定时 需 事 件 有 发 生 时 就 会 先 检 查 标志 ， 如 果 标 志 位 不 满足 ， 就 立刻 归还 
进程 控制 权 ， 同 时 继续 加 入 期 望 的 下 一 个 定时 需 事 件 。 














(4) 如 果 阻 塞 方法 完全 无 法 继续 划分 ， 则 必须 使 用 独立 的 进程 执 


行 这 个 阻塞 方法 


如 果 某 个 方法 调用 时 可 能 导致 进程 休眠 ， 或 者 占用 进程 时 间 过 长 ， 
可 是 又 无 法 将 该 方法 分 解 为 不 阻塞 的 方法 ， 那 么 这 种 情况 是 与 事件 驱动 
架构 相 违 背 的 。 通 利 是 由 于 这 个 方法 的 实现 者 没有 开放 非 阻 蜜 接口 所 导 
致 ， 这 时 必须 通过 产生 新 的 进程 或 者 指定 东 个 非 事 件 分 发 者 进程 来 执行 
阻塞 方法 ， 并 在 阻塞 方法 执行 完毕 时 向 事件 收集 、 分 发 者 进程 发 送 事件 
通知 继续 执行 。 因 此 ， 至 少 要 拆 分 为 两 个 阶段 : 阻塞 方法 执行 前 阶段 、 
阻 玛 方法 执行 后 阶段 ， 而 阻塞 方法 的 执行 要 使 用 单独 的 进程 去 调度 ， 并 
在 方法 返回 后 发 送 事件 通知 。 一 旦 出 现 上 面 这 种 设计 ， 我 们 必须 审视 这 
样 的 事件 消费 者 是 否 足 够 合理 ， 有 没有 必要 用 这 种 违反 事件 驱动 染 构 的 
方式 来 解决 阻 紧 问题 。 




















请 求 的 多 阶段 异步 处 理 将 会 提高 网 络 性 能 、 降 低 请 求 的 时 延 ， 在 与 
事件 驱动 染 构 配合 工作 后 ， 可 以 使 得 Web 服 务 占 同时 处 理 十 万 甚至 特 万 
级 别 的 并 发 连接 ， 我 们 在 开发 Nginx 模 块 时 必须 遵循 这 一 原则 。 





8.2.4 管理 进程 、 多 工作 进程 设计 


Nginx 采 用 一 个 master 管 理 进 程 、 多 个 worker 工 作 进 程 的 设计 方式 ， 
如 图 8-5 所 示 。 






cache 
manacer 


进程 


图 8-5 Nginx 采 用 的 一 个 master 管 理 进程 、 多 个 工作 进程 的 设计 方式 


NN 


在 图 8-5 中 ， 包 括 完 全 相同 的 worker 进 程 、1 个 可 选 的 cache manager 


进程 以 及 1 个 可 选 的 cache loader 进 程 。 
这 种 设计 带 来 以 下 优点 : 
(1) 利用 多 核 系 统 的 并 发 处 理 能 力 


现代 操作 系统 已 经 文 持 多 核 CPU 架 构 ， 这 使 得 多 个 进程 可 以 占用 不 
同 的 CPU 核心 来 工作 。 如 果 只 有 一 个 进程 在 处 理 请 求 ， 则 必然 会 造成 
CPU 资 源 的 浪费 ! 如 果 多 个 进程 间 的 地 位 不 平等 ， 则 必然 会 有 某 一 级 同 
一 地 位 的 进程 成 为 瓶 贷 ， 因 此 ，Nginx 中 所 有 的 worker 工 作 进 程 都 是 完 
全 平等 的 。 这 提高 了 网 络 性 能 、 降 低 了 请 求 的 时 延 。 


(2) 负载 均衡 


多 个 worker 工 作 进 程 间 通过 进程 间 通 信 来 实现 负载 均衡 ， 也 就 是 
说 ， 一 个 请 求 到 来 时 更 容易 被 分 配 到 负载 较 轻 的 worker 工 作 进程 中 处 
理 。 这 将 降低 请 求 的 时 延 ， 并 在 一 定 程度 上 提高 网 络 性 能 。 


(3) 管理 进程 会 负 贡 监控 工作 进程 的 状态 ， 并 负责 管理 其 行为 





管理 进程 不 会 占用 多 少 系统 资源 ， 它 只 是 用 来 局 动 、 停 止 、 监 控 或 
使 用 其 他 行为 来 控制 工作 进程 。 首 先 ， 这 提高 了 系统 的 可 靠 性 ， 妆 工作 
进程 出 现 问题 时 ， 管 理 进程 可 以 司 动 新 的 工作 进程 来 避免 系统 性 能 的 下 
降 。 其 次 ， 管 理 进程 文 持 Nginx 服 务 运行 中 的 程序 升级 、 配 置 项 的 修改 
等 操作 ， 这 种 设计 使 得 动态 可 扩展 性 、 动 态 定制 性 、 动 态 可 进化 性 较 容 








易 实 现 。 


8.2.5 ”平台 无 天 的 代码 实现 


在 使 用 C 语 言 实 现 Nginx 时 ， 尽 量 减少 使 用 与 操作 系统 平台 相关 的 代 
码 ， 如 某 个 操作 系统 上 的 第 三 方 库 。Nginx 重 新 封装 了 日 志 、 各 种 基本 
数据 结构 (如 第 7 章 中 介绍 的 容器 ，、 常 用 算法 等 工具 软件 ， 在 核心 代 
码 都 使 用 了 与 操作 系统 无 天 的 代码 实现 ， 在 与 操作 系统 相关 的 系统 调用 
上 则 分 别针 对 各 个 操作 系统 都 有 独立 的 实现 ， 这 最 终 造 就 了 Nginx 的 可 
移植 性 ， 实 现 了 对 主流 操作 系统 的 文 持 。 








8.2.6 ”内 存 池 的 设计 


为 了 避免 出 现 内 存 人 雄 片 、 减 少 回 操 作 系 统 申请 内 存 的 次 数 、 降 低 各 
个 模块 的 开发 复杂 度 ，Nginx 设 计 了 简单 的 内 存 池 。 这 个 内 存 池 没 有 很 
复杂 的 功能 : 通 芝 它 不 负责 回收 内 存 池 中 已 经 分 配 出 的 内 存 。 这 种 内 存 
池 最 大 的 优点 在 于 : 把 多 次 回 系 统 申请 内 存 的 操作 整合 成 一 次 ， 这 大 大 
减少 了 CPU 资源 的 消耗 ， 同 时 减少 了 内 存 雁 片 。 








因此 ， 通 常 每 一 个 请 求 都 有 一 个 这 种 简易 的 独立 内 存 池 在 第 9 章 
中 会 看 到 ，Nginx 为 每 一 个 TCP 连 接 都 分 配 了 1 个 内 存 池 ， 而 在 第 10 章 和 
第 11 章 ，HTTP 框 架 为 每 一 个 HTTP 请 求 又 分 配 了 1 个 内 存 池 ) ， 而 在 请 


求 结 束 时 则 会 销毁 整个 内 存 池 ， 把 曾经 分 配 的 内 存 一 次 性 归还 给 操作 系 
统 。 这 种 设计 大 大 提高 了 模块 开 友 的 简单 性 (如 在 前 儿 半 中 开发 HTTP 
模块 时 ， 申 请 内 存 后 都 不 用 关心 它 释 放 的 问题 )》， 而 且 因 为 分 配 内 存 次 
数 的 减少 使 得 请 求 执行 的 时 延 得 到 了 降低 ， 同 时 ， 通 过 减少 内 存 雁 片 ， 
提高 了 内 存 的 有 效 利用 率 和 系统 可 处 理 的 并 发 连接 数 ， 从 而 增强 了 网 络 
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8.2.7 ”使 用 统一 管道 过 滤器 模式 的 HTTP 过 滤 模 块 


有 一 类 HTTP 模 块 被 命名 为 HTTP 过 滤 模 块 ， 其 中 每 一 个 过 滤 模 块 都 
有 输入 端 和 输出 端 ， 这 些 输入 端 和 输出 端 都 具有 统一 的 接口 。 这 些 过 滤 
模块 将 按照 configure 执 行 时 决定 的 顺序 组 成 一 个 流水 线 式 的 加 工 HTTP 
响应 的 中 心 ， 每 一 个 过 滤 模 块 都 是 完全 独立 的 ， 它 处 理 着 输入 端 接收 到 
的 数据 ， 并 由 输出 端 传递 给 下 一 个 过 滤 模 块 。 个 过 滤 模 块 都 必须 可 
以 增 量 地 处 理 数据 ， 也 就 是 说 能 够 正确 处 理 完整 数据 流 的 一 部 分 。 





这 种 统一 管理 过 滤器 的 设计 方式 的 好 处 非常 明显 : 首先 它 允 许 把 整 
个 HITP 过 滤 系 统 的 输入 /输出 简化 为 一 个 个 过 滤 模 块 的 简单 组 合 ， 这 大 
大 提高 了 简单 性 ， 其 次 ， 它 提供 了 很 好 的 可 重用 性 ， 任 意 两 个 HTTP 过 
滤 模 块 都 可 以 连接 在 一 起 (在 可 允许 的 范围 内 ) ; 再 次 ， 整 个 过 滤 系 统 
非常 容易 维护 、 增 强 。 例 如 ， 开 发 了 一 个 新 的 过 滤 模 块 后 ， 可 以 非常 方 
便 地 添加 到 过 小 系 统 中 ， 这 是 一 种 高 可 扩展 性 。 又 如 ， 旧 的 过 小 模块 可 





以 很 容易 地 被 升级 版 的 过 滤 模 块 所 丛 代 ， 这 是 一 种 高 可 进化 性 ， 接 着 ， 
它 在 可 验证 性 和 可 测试 性 上 非常 友好 ， 我 们 可 以 灵活 地 变动 这 个 过 小 模 
块 流水 线 来 验证 功能 ， 最 后 ， 这 样 的 系统 完全 文 持 并 发 执行 。 


8.2.8 ”其 他 一 些 用 户 模块 


Nginx 还 有 许多 特定 的 用 户 模 块 都 会 改进 8.1 节 中 提 到 的 约束 属性 。 
例如 ，ngx_http_stub_status_module 模 块 提供 对 所 有 HTTP 连 接 状 态 的 监 
控 ， 这 就 提高 了 系统 可 见 性 。 而 ngx_http_gzip_filter_module 过 滤 模 块 和 
ngx_http_gzip_static_module 模 块 使 得 相同 的 吞吐 量 传送 了 更 多 的 信息 ， 
自然 也 就 提高 了 网 络 效率 。 我 们 也 可 以 开发 这 样 的 模块 ， 让 Nginx 变 得 
更 好 。 

















8.3 ”Nginx 框 架 中 的 核心 结构 体 ngx_cycle_t 


Nginx 核 心 的 框架 代码 一 直 在 围绕 着 一 个 结构 体 展开 ， 它 就 是 
ngx_cycle_t。 无 论 是 master 管 理 进程 、worker 工 作 进程 还 是 cache 
manager (loader〉 进程 ， 每 一 个 进程 都 训 无 例外 地 拥有 唯一 一 个 
ngx_cycle_t 结 构 体 。 服 务 在 初始 化 时 就 以 ngx_cycle_t 对 象 为 中 心 来 提供 
服务 ， 在 正常 运行 时 仍然 会 以 ngx_cycle_t 对 象 为 中 心 。 本 节 将 围绕 着 
ngx_cycle_t 结 构 体 的 定义 、ngx_cycle_t 结 构 体 所 支持 的 方法 来 介绍 
Nginx 框 架 代 码 ， 其 中 8.4 节 中 的 Nginx 的 启动 流程 、8.5 节 和 8.6 节 中 
Nginx 各 进程 的 主要 工作 流程 都 是 以 ngx_cycle_t 结 构 体 作为 基础 的 。 下 
面 我 们 来 看 一 下 ngx_cycle_t 究 范 有 哪些 成 员 维 持 了 Nginx 的 基本 框架 。 





8.3.1 ngx_listening_t 结 构 体 


作为 一 个 Web 服务器 ，Nginx 首 先 需 要 监听 端口 并 处 理 其 中 的 网 络 
事件 。 这 本 来 应 该 属于 第 9 章 所 介绍 的 事件 模块 要 处 理 的 内 容 ， 但 由 于 
监听 端口 这 项 工作 是 在 Nginx 的 局 动 框架 代码 中 完成 的 ， 所 以 暂时 把 它 
放 到 本 章 中 介绍 。ngx_cycle_t 对 象 中 有 一 个 动态 数组 成 员 叫 做 
listening， 它 的 每 个 数组 元 系 都 是 ngx_listening_t 结 构 体 ， 而 每 个 
ngx_jlistening_t 结 构 体 又 代表 着 Nginx 服 务 器 监听 的 一 个 端口 。 在 8.3.2 节 
中 的 一 些 方法 会 使 用 ngx_listening_t 结 构 体 来 处 理 要 监听 的 端口 ， 在 8.4 





节 中 我 们 也 会 看 到 master 进 程 、worker 进 程 等 许多 进程 如 何 监 听 同 一 个 
TCP 问 口 〈fork 出 的 子 进程 自然 共 孚 打开 的 端口 ) 。 更 多 关于 
ngx_listening_t 的 介绍 将 在 第 9 间 中 介绍 。 本 节 我 们 仪 仪 介绍 
ngx_listening_t 的 成 员 ， 对 于 它 会 引用 到 的 其 他 对 象 ， 如 
ngx_connection_t 等 ， 将 在 第 9 章 中 介绍 。 下 面 来 看 一 下 ngx_listening t 的 


成 员 ， 代 码 如 下 所 示 。 





typedef struct ngx_ listening s ngx_ listening_t; 
struct ngx_listening s { 
// Socket 套 接 字 句柄 


ngx_socket_t fd; 
// 监听 


sockaddr 地 址 


struct sockaddr *sockaddr; 
// sockaddr 地 址 长 度 


socklen_t socklen; 
/* 存 储 


IP 地 址 的 字符 串 


addr_text 最 大 长 度 ， 即 它 指定 了 


addr_text 所 分 配 的 内 存 大 小 


*/ 
size_t addr_text_max_len,; 
// 以 字符 囊 形 式 存 储 





IP 地 址 


ngx_str_t addr_text; 


// 套 接 字 类 型 。 例 如 ， 当 


type 是 


SOCK_STREAM 时 ， 表 示 


TCP 
int type; 
A*TCP 实 现 监 听 时 的 


backlog 队 列 ， 它 表示 允许 正在 通过 三 次 握手 建立 


TCP 连 接 但 还 没有 任何 进程 开始 处 理 的 连接 最 大 个 数 


*/ 
int backlog; 
// 内 核 中 对 于 这 个 套 接 字 的 接收 缓冲 区 大 小 


int rcvbuf; 
// 内 核 中 对 于 这 个 套 接 字 的 发 送 缓冲 区 大 小 


int Sndbuf 
// 当 新 的 


TCP 连 接 成 功 建立 后 的 处 理 方 法 


ngx_connection_handler_pt handler; 
/* 实 际 上 框架 并 不 使 用 


Servers 指 针 ， 它 更 多 是 作为 一 个 保留 指针 ， 目 前 主要 用 于 


HTTP 或 者 


mail 等 模块 ， 用 于 保存 当前 监听 端口 对 应 着 的 所 有 主机 名 


2 
void *servers; 
// ]0og 和 


logp 都 是 可 用 的 日 志 对 象 的 指针 


ngx_log_t log; 
ngx_log_t *logp; 
// 如 果 为 新 的 


TCP 连 接 创 建 内 存 池 ， 则 内 存 池 的 初始 大 小 应 该 是 


pool_size 
Size t pool_ size; 
/*TCP_DEFER_ACCEPT 选 项 将 在 建立 


TCP 连 接 成 功 且 接收 到 用 户 的 请 求 数 据 后 ， 才 向 对 监听 套 接 字 感 兴趣 的 进程 发 送 事件 通知 ， 而 连接 建立 成 功 后 ， 如 ， 





post_accept_timeout 秒 后 仍然 没有 收 到 的 用 户 数据 ， 则 内 核 直接 丢弃 连接 


*/ 
ngx_msec_t post_accept_timeout; 
/前 一 个 





ngx_listening_t 结 构 ， 多 个 


ngx_listening_t 结 构 体 之 间 由 


previous 指 针 组 成 单 链表 


*/ 
ngx_listening _t *previous; 
// 当前 监听 句柄 对 应 着 的 


ngx_connection_t 结 构 体 


ngx_connection _t *connection,; 
/* 标 志 位 ， 为 


1 则 表示 在 当前 监听 句柄 有 效 ， 且 执行 


ngx_init_cycle 时 不 关闭 监听 端口 ， 为 


9 时 则 正常 关闭 。 该 标志 位 框架 代码 会 自动 设置 


WA 
unsigned open:1; 
/* 标 志 位 ， 为 


1 表示 使 用 已 有 的 


ngx_cycle_ tt 来 初始 化 新 的 


ngx_cyc1le _t 结 构 体 时 ， 不 关闭 原先 打开 的 监听 端口 ， 这 对 运行 中 升级 程序 很 有 用 ， 


remain 为 


日 时， 表示 正常 关闭 曾经 打开 的 监听 端口 。 该 标志 位 框架 代码 会 自动 设置 ， 参 见 


ngx_init_cycle 方 法 


2 
unsigned remain:1; 
/* 标 志 位 ， 为 


1 时 表示 跳 过 设置 当前 


ngx_listening_t 结 构 体 中 的 套 接 字 ， 为 


0 时 正常 初始 化 套 接 字 。 该 标志 位 框架 代码 会 自动 设置 


“A/ 
unsigned ignore:1; 
// 表示 是 否 已 经 绑 定 。 实 际 上 目前 该 标志 位 没有 使 用 
unsigned bound:1; /* 已 经 绑 定 

*/ 


/* 表 示 当 前 监听 句柄 是 否 来 自前 一 个 进程 (如 升级 


Nginx 程 序 ) ， 如 果 为 


1， 则 表示 来 自前 一 个 进程 。 一 般 会 保留 之 前 已 经 设置 好 的 套 接 字 ， 不 做 改变 


2 
unsigned inherited:1; /* 来 自前 一 个 进程 


*/ 
// 目前 未 使 用 


unsigned nonblocking_accept:1; 
// 标志 位 ， 为 


1 时 表示 当前 结构 体 对 应 的 套 接 字 已 经 监听 


unsigned listen:1; 
// 表示 套 接 字 是 否 阻塞 ， 目 前 该 标志 位 没有 意义 


unsigned nonblocking:1,; 
// 目前 该 标志 位 没有 意义 


unsigned shared:1; 
// 标志 位 ， 为 


1 时 表示 


Nginx 会 将 网 络 地 址 转变 为 字符 串 形式 的 地 址 


unsigned addr_ntop:1; 





ngx_connection_handler_pt 类 型 的 handler 成 员 表 示 在 这 个 监听 端口 上 
成 功 建 立新 的 TCP 连 接 后 ， 就 会 回调 handler 方 法 ， 它 的 定义 很 简单 ， 如 
下 所 未 





typedef void (*ngx_connection_handler_pt)(ngx_connection t *c); 








它 接收 一 个 ngx_connection_t 连 接 参 数 。 许 多 事件 消费 模块 〈 如 
HTTP 框 架 、mail 框 架 〉 都 会 目 定 义 上 面 的 handler 方 法 。 


8.3.2 ngx_cycle_t 结 构 体 


Nginx 框 架 是 围绕 着 ngx_cycle_t 结 构 体 来 控制 进程 运行 的 。 
ngx_cycle_t 结 构 体 的 prefix、conf_prefix、conf _file 等 字符 串 类 型 成 员 保 
存 着 Nginx 配 置 文件 的 路 径 ， 从 8.2 节 已 经 知道 ，Nginx 的 可 配置 性 完全 
依赖 于 nginx.conf 配 置 文件 ，Nginx 所 有 模块 的 可 定制 性 、 可 伸缩 性 等 诸 
多 特性 也 是 依赖 于 nginx.conf 配 置 文件 的 ， 可 以 想见 ， 这 个 配置 文件 路 
径 必然 是 保存 在 ngx_cycle_t 结 构 体 中 的 。 


有 了 配置 文件 后 ，Nginx 框 架 束 开始 根据 配置 项 来 加 载 所 有 的 模块 
了 ， 这 一 步骤 会 在 ngx_init_cycle 方 法 中 进行 〈 见 8.3.3 节 ) 。 
ngx_init_cycle 方 法 ， 顾 名 思 义 ， 就 是 用 来 构造 ngx_cycle_t 结 构 体 中 成 员 
的 ， 首 先 来 介绍 一 下 ngx_cydle_t 中 的 成 员 ( 对 于 下 面 提 到 的 
connections、read_events、write_events、files、free_connections 等 成 
员 ， 它 们 是 与 事件 模块 强 相 关 的 ， 本 章 将 不 做 详细 介绍 ， 在 第 9 章 中 会 
详 述 这 些 成 员 的 意义 ) 。 

















typedef struct ngx_cycle s ngx_cycle t; 
Struct ngx_cycle s { 
/* 保 存 着 所 有 模块 存储 配置 项 的 结构 体 的 指针 ， 它 首先 是 一 个 数组 ， 每 个 数组 成 员 又 是 一 个 指针 ， 这 个 指针 





VOlid**** “f/f 
void ****conf_ctx; 
// 内 存 池 


ngx_pool_t *pool; 
/* 日 志 模 块 中 提供 了 生成 基本 


ngx_10og_t 日 志 对 象 的 功能 ， 这 里 的 


10g 实 际 上 是 在 还 没有 执行 


ngx_init_cycle 方 法 前 ， 也 就 是 还 没有 解析 配置 前 ， 如 果 有 信息 需要 输出 到 上 日志， 就 会 暂时 使 用 


10og 对 象 ， 它 会 输出 到 屏幕 。 在 


ngx_init_cycle 方 法 执行 后 ， 将 会 根据 


nginx.conf 配 置 文件 中 的 配置 项 ， 构 造 出 正确 的 日 志文 件 ， 此 时 会 对 


1l0g 重 新 赋值 


Wd 
ngx_log_t *1o0g; 
/* 由 


nginx.conf 配 置 文件 读 取 到 日 志文 件 路 径 后 ， 将 开始 初始 化 


error_1og 日 志文 件 ， 由 于 


10g 对 象 还 在 用 于 输出 日 志 到 屏幕 ， 这 时 会 用 


new_1og 对 象 暂时 性 地 替代 


10g 日 志 ， 待 初始 化 成 功 后 ， 会 用 


new_1og 的 地 址 履 盖 上 面 的 


lo0g 指 针 


*/ 
ngx_log_t new_ log; 
// 与 下 面 的 


files 成 员 配 合 使 用 ， 指 出 


files 数 组 里 元 素 的 总 数 


ngx_uint_t files_n; 
/对 于 


poll、 


rtSsig 这 样 的 事件 模块 ， 会 以 有 效 文件 句柄 数 来 预先 建立 这 些 





ngx_connection + 结构 体 ， 以 加 速 事件 的 收集 、 分 发 。 这 时 


files 就 会 保存 所 有 


ngx_connection tt 的 指针 组 成 的 数组 ， 


files_n 就 是 指针 的 总 数 ， 而 文件 句 酉 的 值 用 来 访问 


files 数 组 成 员 


*/ 
ngx_connection t **files; 
// 可 用 连接 池 ， 与 


free_connection_n 配 合 使 用 


ngx_connection _t *free_connections ; 
// 可 用 连接 池 中 连接 的 总 数 


ngx_uint_t free connection_n,; 
/* 双 向 链表 容器 ， 元 素 类 型 是 


ngx_connection_t 结 构 体 ， 表 示 可 重复 使 用 连接 队列 





*7/ 
ngx_queue_t reusable_ connections_queue; 
/* 动 态 数 组 ， 每 个 数组 元 素 存储 着 


ngx_listening_t 成 员 ， 表 示 监 听 端 口 及 相关 的 参数 


«7 
ngx_array_t listening; 
/* 动 态 数 组 容器 ， 它 保存 着 


Nginx 所 有 要 操作 的 目录 。 如 果 有 目录 不 存在 ， 则 会 试图 创建 ， 而 创建 目录 失败 将 会 导致 


Nginx 启 动 失败 。 例 如 ， 上 传 文件 的 临时 目录 也 在 


pathes 中 ， 如 果 没 有 权限 创建 ， 则 会 导致 


Nginx 无 法 启动 


4 
ngx_array_t pathes 
/* 单 链表 容器 ， 元 素 类 型 是 


ngx_open_file t 结 构 体 ， 它 表示 


Nginx 忆 经 打开 的 所 有 文件 。 事 实 上 ， 


Nginx 框 架 不 会 向 


open_files 链 表 中 添加 文件 ， 而 是 由 对 此 感 兴趣 的 模块 向 其 中 添加 文件 路 径 名 ， 


Nginx 框 架 会 在 


ngx_init_cycle 方 法 中 打开 这 些 文件 


* 

/ 
ngx_list_t open_ files,; 
/* 单 链表 容器 ， 元 素 的 类 型 是 


ngx_shm_zone_t 结 构 体 ， 每 个 元 素 表示 一 块 共享 内 存 ， 共 享 内 存 将 在 第 


14 章 介绍 


*/ 
ngx_list_t shared memory; 
// 当前 进程 中 所 有 连接 对 象 的 总 数 ， 与 下 面 的 


connections 成 员 配 合 使 用 


ngx_uint_t connection_n; 
// 指向 当前 进程 中 的 所 有 连接 对 象 ， 与 


connection_n 配 合 使 用 


ngx_connection _t *connections ; 
// 指向 当前 进程 中 的 所 有 读 事件 对 象 ， 





connection_n 同 时 表示 所 有 读 事 件 的 总 数 


ngx_event_t *read_events 
// 指向 当前 进程 中 的 所 有 写 事件 对 象 ， 





connection_n 同 时 表示 所 有 写 事件 的 总 数 


ngx_event_t *write events; 
/* 旧 的 


ngx_cycle_t 对 和 象 用 于 引用 上 一 个 


ngx_cycle_t 对 象 中 的 成 员 。 例 如 


ngx_init_cycle 方 法 ， 在 启动 初期 ， 需 要 建立 一 个 临时 的 


ngXx_cycle_t 对 象 保存 一 些 交 量 ， 再 调用 


ngx_init_cycle 方 法 时 就 可 以 把 旧 的 


ngx_cycle_t 对 和 象 传 进去 ， 而 这 时 


01ld_cycle 对 象 就 会 保存 这 个 前 期 的 


ngx_cycle 七 对 象 





*/ 

ngx_cycle _t *old cycle; 

// 配置 文件 相对 于 安装 目录 的 路 径 名 称 

ngx_str_t conf_file; 

A/*Nginx 处 理 配 置 文件 时 需要 特殊 处 理 的 在 命令 行 携带 的 参数 ， 一 般 
-g 选 项 携带 的 参数 
*/ 


ngx_str_t conf_param; 
// Nginx 配 置 文 件 所 在 目录 的 路 径 


ngx_str_t conf_prefix; 
// Nginx 安 装 目 录 的 路 径 


ngx_str_t prefix; 
// 用 于 进程 间 同步 的 文件 锁 名 称 


ngx_str_t lock_file; 
// 使 用 


gethostname 系 统 调 用 得 到 的 主机 名 


ngx_str_t hostname 





在 构造 ngx_cycle_t 结 构 体 成 员 的 ngx_init_cycle 方 法 中 ， 上 面 所 列 出 
的 pool 内 存 池 成 员 、hostname 主 机 名 、 日 志文 件 new_log 和 log、 存 储 所 
有 路 径 的 pathes 数 组 、 共 享 内 存 、 监 听 端 口 等 都 会 在 该 方法 中 初始 化 。 
本 章 后 续 提 到 的 流程 、 方 法 中 可 以 随处 见 到 ngx_cycle _t 结 构 体 成 员 的 身 


i 
奈 和 。 





8.3.3 ngx_cycle ft 支持 的 方法 


与 ngx_cycle_t 核 心 结构 体 相关 的 方法 实际 上 是 非常 多 的 。 例 如 ， 
个 模块 都 可 以 通过 init_module、init_process、exit_process、exit_master 
等 方法 操作 进程 中 独 有 的 ngx_cycle_t 结 构 体 。 然 而 ，Nginx 的 框架 代码 
中 关于 ngx_cycle_t 结 构 体 的 方法 并 不 是 太 多 ， 表 8-2 中 列 出 了 与 
ngx_cycle_t 相 关 的 主要 方法 ， 我 们 先 做 一 个 初步 的 介绍 ， 在 后 面 的 章节 
中 将 会 提 到 这 些 方法 的 意义 。 





表 8-2 中 列 出 的 许多 方法 都 可 以 在 下 面 各 节 中 找到 。 例 如 ， 


ngx_init_cycle 方 法 的 流程 可 参照 图 8-6 中 的 第 3 步 ( 调 用 所 有 核心 模块 的 
create_conf 方 法 ) ~ 第 8 步 ( 调 用 所 有 模块 的 init_module 方 法 ) 之 间 的 内 
容 ; ngx_worker_process_cycle 方 法 可 部 分 参照 图 8-7( 图 8-7 中 缺少 调用 


ngx_worker_process_init 方 法 ) ; ngx_master_process_cycle 监 控 、 管 理子 


进程 的 流程 可 参照 图 8-8。 


表 8-2 ngx_cycle_t 结 构 体 支持 的 主要 方法 


方法 名 执行 意义 

返回 初始 化 成 功 的 完整 的 ngx_eycle_ 
t 结 构 体 ， 该 函数 将 会 负责 初始 化 ngx_ 
cycle t 中 的 数据 结构 、 解 析 配 置 文件 、 
加 载 所 有 模块 、 打 开 监 昕 端口、 初始 化 
进程 间 通 信 方 式 等 工作 - 如 果 失 败 ， 则 
返回 NULL 空 指针 

用 运行 Nginx 时 可 能 携带 的 目录 参数 

ngx_int_ t ngx_process_options | cycle 通常 是 刚刚 分 配 的 ngx_cycle t 结 构 | 来 初始 化 cycle， 包 括 初 始 化 运行 目录 、 
(ngx_cycle ts*cycle) 体 指针 ， 仅 用 于 传递 配置 文件 路 径 信息 “| 配置 目录 ,并 生成 完整 的 nginx.conf 配 
园 文 件 路 径 

在 执行 不 重启 服务 升级 Nginx 的 操作 
时 ， 老 的 Nginx 进程 会 通过 环境 变量 

ngx_int t ngx_add_inherited| cycle 是 当前 进程 的 ngx_cycle 1 结构 | "NGINX” 来 传递 需要 打开 的 监听 端 
sockets(ngx cycle t *cycle) 体 指 针 口 ， 新 的 Nginx 进程 会 通过 ngx add_ 
inherited_sockets 方法 来 使 用 已 经 打开 
的 TCP 监听 端口 
ngx_int t ngx_open_listening_ | cycle 是 当前 进程 的 ngx_cycle t 结 构 | 监听 、 绑 定 cycle 中 listening 动态 数 


old_cycle 表示 临时 的 ngx cyclet 指 
针 ， 一般 仅 用 来 传递 ngx_cycle t 结 构 
体 中 的 配置 文件 路 径 等 参数 


ngx_cycle t *ngx_init cycle 
(ngx_cycle t *old cycle) 


sockets (ngx_cycle t *cycle) 体 指针 组 指定 的 相应 端口 

void ngx_configure_listening_| cycle 是 当前 进程 的 ngx_cycle t 结 构 | 根据 nginx.conf 中 的 配置 项 设置 已 经 
sockets(ngx cycle t *cycle) 体 指针 监听 的 句柄 

void ngx_close listening cycle 是 当前 进程 的 ngx_cycle + 结构 | 关闭 cycle 中 listening 动态 数组 已 经 





SOckets(ngX_cycle t *cycle) 体 指针 打开 的 句柄 


void ngx_master process __ Se 是 当前 进程 的 ngx_cycle t 结构 进入 master 进程 的 工作 循环 
cycle(ngx_cycle t *cycle) 体 指 针 


void ngx_single_process_cycle| cycle 是 当前 进程 的 ngx_cycle t 结 构 | 进入 单 进程 模式 ( 非 master、worker 
(ngx_cycle t *cycle) 体 指针 进程 工作 模式 ) 的 工作 循环 
cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 , n 是 启动 子 进程 的 个 数 ，type 
是 启动 方式 ， 它 的 取 值 范围 有 以 下 5 个 : 
1 ) NGX PROCESS RESPAWN; 
void ngx_start worker | 2)NGOGX PROCESS NORESPAWN; 
processes (ngx _ cycle t *cycle,| 3) NGX PROCESS JUST SPAWN:; 
ngx_int tn, ngx_int t type) 4) NGX PROCESS JUST RESPAWN:; 
5) NGX PROCESS DETACHED. 
type 的 值 将 影响 8.6 节 中 ngx_process t 结 
构 体 的 respawn、detached、just_spawn 标 
志 位 的 值 


启动 n 个 worker 子 进程 ， 并 设置 好 
每 个 子 进 程 与 master 父 进程 之 间 使 用 
socketpair 系统 调用 建立 起 来 的 socket 
句柄 通信 机 制 





方法 名 


void ngx_start cache 
manager processes(ngx cycle t 
*cycle, ngx_uint t respawn) 


void ngx _ pass open channel 
(ipx_ cyele t eycle, gx 
channel t *ch) 

Void ngx_signal worker processes 
(ngx_ cycle t *cycle, int signo) 


ngx uint t ngx reap_children 
(ngx_cycle t*cycle) 


voidngx_master_process_ exit 
(ngx_ cycle t *cycle) 


void ngx_ worker process cycle 
(ngx_cycle t *cycle, void *data) 


void ngx worker process init 
(ngx cycle t *cycle, ngx uint t 
priority) 

void ngx worker process exit 
(ngx_cycle t *cycle) 

void ngx _ cache manager_ 
process cycle(ngx cycle t *cycle, 
void *data) 


void ngx_ process events and_ 
timers (ngx_cycle t *cycle) 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 ,respawn 是 启动 子 进程 的 方式 ， 
它 与 ngx_start_worker_processes 方法 中 
的 type 参数 意义 完全 相同 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 ，ch 是 将 要 向 子 进程 发 送 的 信息 


cycle 是 当前 进程 的 ngx_cycle t 结构 
体 指针 ，signo 是 信号 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 

cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指 针 ， 这 里 还 未 开始 使 用 data 参数 ， 
所 以 data 一 般 为 NULL 

cycle 是 当前 进程 的 ngx_cycle 1 结构 
体 指针 ，priority 是 worker 进程 的 系统 
优先 级 

cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 

cycle 是 当前 进程 的 ngx_cyclet 结 
构 体 指针 ，data 是 传人 的 ngx_cache_ 
manager_ctx_t 结构 体 指针 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 





( 续 ) 
执行 意义 

根据 是 否 使 用 文件 缓存 模块 ， 也 就 是 
cycle 中 存储 路 径 的 动态 数组 中 是 否 有 路 
径 的 manage 标志 打开 ， 来 决定 是 否 启 动 
cache manage 子 进程 ， 同 样 根据 loader 
标志 决定 是 否 启动 cache loader 子 进 程 

癌 所 有 已 经 打开 的 channel{( 通 过 
socketpair 生成 的 句柄 进行 通信 ) 发 送 
ch 信息 


处 理 worker 进程 接收 到 的 信和 号 


检查 master 进程 的 所 有 子 进 程 ， 根 
据 每 个 子 进程 的 状态 ( ngx_process { 结 
构 体 中 的 标志 位 ) 判断 是 否 要 启动 子 进 
程 、 更 改 pid 文件 等 


退出 master 进程 工作 的 循环 


进入 worker 进程 工作 的 循环 


进入 worker 进程 工作 循环 之 前 的 初 
始 化 工作 


退出 worker 进程 工作 的 循环 


执行 缓存 管理 工作 的 循环 方法 。 这 与 
文件 缓存 模块 密切 相关 ， 在 本 章 中 不 做 
详细 探讨 

使 用 事件 模块 处 理 截止 到 现在 已 经 收 
集 到 的 事件 。 该 函数 由 事件 模块 实现 ， 
详 见 第 9 章 


8.4 ”Nginx 启 动 时 框架 的 处 理 流程 


通过 阅读 8.3 节 ， 读 者 应 该 对 ngx_cycle_t 结 构 体 有 了 基本 的 了 解 ， 下 
面 继续 介绍 Nginx 在 局 动 时 框架 做 了 些 什么 。 注 意 ， 本 节 描 述 的 Nginx 局 
动 流程 基本 上 不 包含 Nginx 模 块 在 局 动 流程 中 所 做 的 工作 ， 仅 仅 是 展示 
框架 代码 如 何 使 服务 运行 起 来 ， 这 里 的 框架 主要 就 是 调用 表 8-2 中 列 出 
的 地 ;二 5 





如 图 8-6 所 示 ， 这 里 包括 Nginx 框 架 在 启动 阶段 执行 的 所 有 基本 流 
程 ， 零 碎 的 工作 这 里 不 涉及 ， 对 一 些 复杂 的 业务 也 仅 做 简单 说 明 (如 图 
8-6 中 的 第 2 步 涉及 的 平滑 升级 的 问题 )》， 本 节 关 注 的 重点 只 是 Nginx 的 
正常 启动 流程 。 





1 ) 根 据 命令 行 得 到 
配置 文件 路 径 








2 ) 如 果 处 于 升级 中 ， 则 监听 环境 
变量 里 传递 的 监听 句柄 
















3 ) 调用 所 有 核心 模块 的 create_conf 方 法 
生成 存放 配置 项 的 结构 体 









4) 针对 所 有 核心 模块 解析 
nginx conf 配 告 文件 









5) 调用 所 有 核心 模块 的 


init _conf 方 法 










6 ) 创 建 目 录 、 打 开 文 件 、 初 始 化 共享 
内 存 等 进程 间 通 信 方 式 










7) 打 开 由 各 Nginx 模块 从 配置 文件 
中 读 取 到 的 监听 端口 









8) 调用 所 有 模块 的 
init _module 方 法 
[检测 Nginx 运 行 方 式 ] 


[以 单 进程 方式 运行 Nginx] 
« 9) 进 入 single 模式 


[以 master 多 进程 方式 运行 Nginx ] 










[多 进程 并 发 执行 ] 


10) 调用 所 有 模块 的 init_process 方 法 





N 


14) 启动 cache manager 进 程 12 ) 启动 worker 进 程 11 ) master 进程 


13 ) 调用 所 有 模块 的 init_process 方 法 












15 ) 启动 cache loader 子 进程 


& 
二 
1 





16) 关闭 父 进程 启动 时 
监听 的 端口 








图 8-0 Neginx 启 动 六 过 程 的 流程 图 


下 面 简要 介绍 一 下 图 8-6 中 的 主要 步骤 : 


1) 在 Nginx 局 动 时 ， 首 先 会 解析 命令 行 ， 处 理 各 种 参数 。 因 为 
Nginx 古 以 配置 文件 作为 核心 提供 服务 的 ， 所 以 最 主要 的 就 是 确定 配置 
文件 nginx.conf 的 路 径 。 这 里 会 预先 创建 一 个 临时 的 ngx_cycle_t 关 型 变 
量 ， 用 它 的 成 员 存 储 配置 文件 路 径 〈 实 际 上 还 会 使 用 这 个 临时 
ngx_cycle_t 结 构 体 的 其 他 成 员 ， 如 log 成 员 会 指向 屏幕 输出 日 志 ) ， 最 后 
调用 表 8-2 中 的 ngx_process_options 方 法 来 设置 配置 文件 路 径 等 参数 。 





2) 图 8-6 中 的 第 2 步 实 际 上 就 是 在 调用 表 8-2 中 的 
ngx_add_inherited_sockets 方 法 。Nginx 在 不 重启 服务 升级 时 ， 也 就 是 我 
们 说 过 的 平滑 升级 (参见 1.9 节 ) 时 ， 它 会 不 重启 master 进 程 而 启动 新 版 
本 的 Nginx 程 序 。 这 样 ， 旧 版 本 的 master 进 程 会 通过 execve 系 统 调 用 来 启 
动 新 版 本 的 master 进 程 〈 先 fork 出 子 进 程 再 调用 exec 来 运行 新 程序 ) ， 这 
时 旧版 本 的 master 进 程 必 须要 通过 一 种 方式 告诉 新 版 本 的 master 进 程 这 
是 在 平滑 升级 ， 并 且 传 递 一 些 必要 的 信息 。Nginx 是 通过 环境 变量 来 传 
递 这 些 信 息 的 ， 新 版 本 的 master 进 程 通过 ngx_add_inherited_sockets 方 法 
由 环境 变量 里 读 取 平 滑 升 级 信息 ， 并 对 旧版 本 Nginx 服 务 监听 的 句柄 做 
继承 处 理 。 











3) 第 3 步 ~ 第 8 步 ， 都 是 在 ngx_init _cycle 方 法 中 执行 的 。 在 初始 化 
ngx_cycle_t 中 的 所 有 容器 后 ， 会 为 读 取 、 解 析 配 置 文件 做 准备 工作 。 
为 每 个 模块 都 必须 有 相应 的 数据 结构 来 存储 配置 文件 中 的 各 配置 项 ， 创 





建 这 些 数 据 结构 的 工作 都 需要 在 这 一 步 进行 。Nginx 框 架 只 关心 
NGX_CORE_MODULE 核 心 模块 ， 这 也 是 为 了 降低 框架 的 复杂 上 度 。 这 里 
将 会 调用 所 有 核心 模块 的 create_conf 方 法 (也 只 有 核心 模块 才 有 这 个 方 
法 ) ， 这 意味 着 需要 所 有 的 核心 模块 开始 构造 用 于 存储 配置 项 的 结构 
体 。 其 他 非 核心 模块 怎么 办 呢 ? 其 实 很 简单 。 这 些 模块 大 都 从 属于 一 个 
核心 模块 ， 如 每 个 HTTP 模 块 都 由 ngx_http_module 管 理 〈 如 图 8-2 所 

示 ) ， 这 样 ngx_http_module 在 解析 自己 感 兴趣 的 “http” 配 置 项 时 ， 将 会 
调用 所 有 HITP 模 块 约 定 的 方法 来 创建 存储 配置 项 的 结构 体 〈 如 第 4 章 中 


介绍 过 的 xxx_create main conf、xxx create srv_conf、 








Xxxx_create loc conf 方 法) 。 


4) 调用 配置 模块 提供 的 解析 配置 项 方法 。 壳 历 nginx.conf 中 的 所 有 
配置 项 ， 对 于 任 一 个 配置 项 ， 将 会 检查 所 有 核心 模块 以 找 出 对 它 感 兴趣 
的 模块 ， 并 调用 该 模块 在 ngx_command_t 结 构 体 中 定义 的 配置 项 处 理 方 
法 。 这 个 流程 可 以 参考 图 4-1。 


5) 调用 所 有 NGX_CORE_MODULE 核 心 模块 的 init_conf 方 法 。 这 
一 步骤 的 目的 在 于 让 所 有 核心 模块 在 解析 完 配 置 项 后 可 以 做 综合 性 处 
理 。 


6) 在 之 前 核心 模块 的 init_ conf 或 者 create_conf 方 法 中 ， 可 能 已 经 有 
些 模块 《如 绥 存 模块 ) 在 ngx_cycle_t 结 构 体 中 的 pathes 动 态 数组 和 
open_files 链 表 中 添加 了 需要 打开 的 文件 或 者 目录 ， 本 步骤 将 会 创建 不 存 


在 的 目录 ， 并 把 相应 的 文件 打开 。 同 时 ，ngx_cycle_t 结 构 体 的 
shared_memory 链 表 中 将 会 开始 初始 化 用 于 进程 间 通 信 的 共享 内 存 。 


7) 之 前 第 4 步 在 解析 配置 项 时 ， 所 有 的 模块 都 已 经 解析 出 自己 需要 
监听 的 端口 ， 如 HTTP 模 块 已 经 在 解析 http{...} 配 置 项 时 得 到 它 要 监 昕 的 
端口 ， 并 添加 到 listening 数 组 中 了 。 这 一 步 又 束 是 按照 listening 数 组 中 的 


每 一 个 ngx_listening_t 元 素 设 置 Socket 句 柄 并 监听 端口 “实际 上 ， 这 一 步 


又 的 主要 工作 束 是 调用 表 8-2 中 的 ngx_open_listening_sockets 方 法 ) 。 


8) 在 这 个 阶段 将 会 调用 所 有 模块 的 init_module 方 法 。 接 下 来 将 会 
根据 配置 的 Nginx 运 行 模式 决定 如 何 工 作 。 


9) 如 果 nginx.conf 中 配置 为 单 进程 工作 模式 ， 这 时 将 会 调用 
ngx_single_process_cycle 方 法 进入 单 进程 工作 模式 。 


10) 调用 所 有 模块 的 init_process 方 法 。 单 进程 工作 模式 的 启动 工作 
至 此 全 部 完成 ， 将 进入 正常 的 工作 模式 ， 也 就 是 8.5 节 和 8.6 节 分 别 介绍 
的 worker 进 程 工作 循环 、master 进 程 工作 循环 的 结合 体 。 

11) 如 果 进 入 master、worker 工 作 模 式 ， 在 启动 worker 子 进程 、 


cache manage 子 进程 、cache loader 子 进程 后 ， 就 开始 进入 8.6 节 提 到 的 工 
作 状 态 ， 至 此 ，master 进 程 启动 流程 执行 完毕 。 


12) 由 master 进 程 按照 配置 文件 中 worker 进 程 的 数目 ， 局 动 这 些 子 


进程 〈 也 就 是 调用 表 8-2 中 的 ngx_start_worker_processes 方 法 ) 。 


13) 调用 所 有 模块 的 init_process 方 法 。worker 进 程 的 启动 工作 至 此 
全 部 完成 ， 接 下 来 将 进入 正常 的 循环 处 理事 件 流 程 ， 也 就 是 8.5 节 中 介 
绍 的 worker 进 程 工作 循环 的 ngx_worker_process_cycle 方 法 。 


14) 在 这 一 步 又 中 ， 由 master 进 程 根据 之 前 各 模块 的 初始 化 情况 来 
决定 是 否 启动 cache manage 子 进程 ， 也 就 是 根据 ngx_cycle_t 中 存储 路 径 
的 动态 数组 pathes 中 是 否 有 某 个 路 径 的 manage 标 志 位 打开 来 决定 是 否 启 
动 cache manage 子 进程 。 如 有 果 有 任何 1 个 路 径 的 manage 标 志 位 为 1， 则 局 
动 cache manage 子 进程 。 





15) 与 第 14 步 相同 ， 如 果 有 任何 1 个 路 径 的 loader 标 志 位 为 1， 则 启 
动 cache loader 子 进程 。 对 于 第 14 步 和 第 15 步 而 言 ， 都 是 与 文件 缓存 模块 
密切 相关 的 ， 但 本 章 不 会 详 述 。 





16) 关闭 只 有 worker 进 程 才 需要 监听 的 端口 。 


在 以 上 16 个 步骤 中 ， 人 简要 地 列举 出 了 Nginx 在 单 进程 模式 和 master 工 
作 方式 下 的 局 动 流 程 ， 这 里 仅 列 举 出 与 Nginx 框 架 密 切 相 关 的 步 又， 并 
未 涉及 具体 的 模块 。 


8.5” ”worker 进程 是 如 何 工 作 的 


本 节 的 内 容 不 会 涉及 事件 模块 的 处 理工 作 ， 只 是 探讨 在 worker 进 程 
中 循环 执行 的 ngx_worker_process_cycle 方 法 是 如 何 控 制 进程 运行 的 。 





master 进 程 如 何 通 知 worker 进 程 停止 服务 或 更 换 日 志文 件 呢 ?对 于 
这 样 控制 进程 运行 的 进程 间 通 信 方 式 ，Nginx 采 用 的 是 信号 〈 详 见 14.5 
节 ) 。 因 此 ，worker 进 程 中 会 有 一 个 方法 来 处 理 信号 ， 它 束 是 


ngx_signal_handler 方 法 。 








void ngx_signal handler(int signo) 





对 于 worker 进 程 的 工作 方法 ngx_worker_process_cycle 来 说 ， 它 会 关 
注 以 下 4 个 全 局 标志 位 。 





sig atomic t ngx_terminate,; 
sig atomic t ngx_quit; 
ngx_uint_t ngx_exiting; 
sig atomic t ngx_reopen,; 














其 中 的 ngx_terminate、ngx_quit、ngx_reopen 都 将 由 
ngx_signal_handler 方 法 根据 接收 到 的 信号 来 设置 。 例 如 ， 当 接收 到 
QUIT 信 号 时 ，ngx_quit 标 志 位 会 设 为 1， 这 是 在 告诉 worker 进 程 需 要 优 


雅 地 关闭 进程 ; 当 接 收 到 TERM 信号 时 ，ngx_terminate 标 志 位 会 设 为 1， 


这 是 在 告诉 worker 进 程 需要 强制 关闭 进程 ， 当 接收 到 USR1 信 号 时 ， 
ngx_reopen 标 志 位 会 设 为 1， 这 是 在 告诉 Nginx 需 要 重新 打开 文件 〈 如 切 


换 日 志文 件 时 ) ， 见 表 8-3。 


表 8-3 worket 进 程 接收 到 的 信号 对 框架 的 意义 


言 ”号 对 应 进程 中 的 全 局 标志 位 变 意 义 
QUIT 优 牙 地 关闭 进 各 
TERM 或 者 INT 强制 关闭 进程 
wi 
WINCH 目前 没有 实际 意义 





ngx_exiting 标 志 位 仅 由 ngx_worker_process_cycle 方 法 在 退出 时 作为 
标志 位 使 用 ， 如 图 8-7 所 示 。 


x exiting 标志 位 为 1, 进程 退出 ] 
se 2 对 当前 所 有 活动 连接 调用 读 事 件 ) 





全 




















方法 处 理 关闭 连接 事件 
[还 有 未 处 理 完 的 事件 ] ds 
[所 有 连接 都 已 关闭 ] 











ngx terminate 人 标记 公 结 VY 
[age_ieoben 为 0] ee cts bn eee, 调用 所 有 模块 的 
exit_proces 咏 法 





[ngx_terminate 为 0] 





et 标志 位 为 1 ,优雅 地 关闭 进程 ] 





V 
[ngx_quit 为 0] 必 关闭 所 有 监听 句柄 并 设置 ) 


ngx _exiting 剑 蕊 

















[ngx_reopen 标 志 位 为 1, 重新 打开 所 有 文件 ] ® 
重新 打开 
所 有 文件 


图 8-7 ”wotket 进 程 正 常 工 作 、 退 出 时 的 流程 图 








在 ngx_worker_process_cycle 方 法 中 ， 通 过 检查 ngx_exiting、 


ngx_terminate、ngx_quit、ngx_reopen 这 4 个 标志 位 来 决定 后 续 动 作 。 


如 果 ngx_exiting 为 1， 则 开始 准备 关闭 worker 进 程 。 首 先 ， 根 据 当前 
ngx_cycle_t 中 所 有 正在 处 理 的 连接 ， 调 用 它们 对 应 的 关闭 连接 处 理 方法 
《就 是 将 连接 中 的 close 标 志 位 置 为 1， 再 调用 读 事件 的 处 理 方法 ， 在 第 9 
章 中 会 详细 讲解 Nginx 连 接 ) 。 调 用 所 有 活动 连接 的 读 事件 处 理 方 法 处 
连接 关闭 事件 后 ， 将 检查 ngx_event_timer_rbtree 红 黑 树 (保存 所 有 事 





件 的 定时 器 ， 在 第 9 章 中 会 介绍 它 ) 是 否 为 室 ， 如 果 不 为 室 ， 表 示 还 有 
事件 需要 处 理 ， 将 继续 向 下 执行 ， 调 用 ngx_process_events_and_timers 方 
法 处 理事 件 ; 如 果 为 空 ， 表 示 已 经 处 理 完 所 有 的 事件 ， 这 时 将 调用 所 有 
模块 的 exit_process 方 法 ， 最 后 销毁 内 存 池 ， 退 出 整个 worker 进 程 。 








@@ 计 意 ng exiting 标 志 位 只 有 唯一 一 段 代码 会 设置 它 ， 也 就 是 下 
面 接收 到 QUIT 信 号 。negx_quit 只 有 在 首次 设置 为 1 时 ， 才 会 将 ngx_exiting 
置 为 1。 


如 果 ngx_exiting 不 为 1， 那 么 调用 ngx_process_events_and_timers 方 
法 处 理事 件 。 这 个 方法 是 事件 模块 的 核心 方法 ， 将 会 在 第 9 章 介绍 它 。 


接 下 来 检查 ngx_terminate 标 志 位 ， 如 果 ngx_terminate 不 为 1， 则 继续 
向 下 检查 ， 否 则 开始 准备 退出 worker 进 程 。 与 上 一 步 ngx_exiting 为 1 的 退 
出 流程 不 同 ， 这 里 不 会 调用 所 有 活动 连接 的 处 理 方法 去 处 理 关 闭 连接 事 
件 ， 也 不 会 检查 是 否 已 经 处 理 完 所 有 的 事件 ， 而 是 立刻 调用 所 有 模块 的 
exit_process 方 法 ， 销 毁 内 存 池 ， 退 出 worker 进 程 。 








接 下 来 再 检查 ngx_quit 标 志 位 ， 如 果 标 志 位 为 1， 则 表示 需要 优雅 地 
关闭 连接 。 这 时 ，Nginx 首 先 会 将 所 在 进程 的 名 字 修 改 为 “worker process 
is shutting down”， 然 后 调用 ngx_close_listening_sockets 方 法 来 关闭 监听 
的 端口 ， 接 着 设置 ngx_exiting 标 志 位 为 1， 继 续 同 下 执行 (检查 


ngx_reopen_files 标 志 位 〉。 


最 后 检查 ngx_reopen 标 志 位 ， 如 果 为 1， 则 表示 需要 重新 打开 所 有 
文件 。 这 时 ， 调 用 ngx_reopen_files 方 法 重新 打开 所 有 文件 。 之 后 继续 下 
一 个 循环 ， 再 去 检查 ngx_exiting 标 志 位 。 


8.6 master 进程 是 如 何 工 作 的 


master 进 程 不 需要 处 理 网 络 事件 ， 它 不 负责 业务 的 执行 ， 只 会 通过 
管理 worker 等 子 进 程 来 实现 重启 服务 、 平 滑 升级 、 更 换 日 志文 件 、 配 置 
文件 实时 生效 等 功能 。 与 8.5 节 类 似 的 是 ， 它 会 通过 检查 以 下 7 个 标志 位 


来 决定 ngx_master_process_cycle 方 法 的 运行 。 














sig_atomic ngx_reap; 
sig_atomic ngx_terminate; 
sig_atomic ngx_quit; 





sig_atomic 
sig_atomic 
sig atomic 
sig_atomic 


ngx_reconfigure; 
ngx_reopen,; 
ngx_change_binary; 
ngx_noaccept,; 











Fer rt 








ngx_signal_handler 方 法 会 根据 接收 到 的 信号 设置 ngx_reap、 
ngx_quit、 ngx_terminate、ngx_reconfigure、ngx_reopen、 


ngx_change_binary、ngx_noaccept 这 些 标志 位 ， 见 表 8-4。 


表 8-4 进程 中 接收 到 的 信号 对 Nginx 框 架 的 意义 


对 应 进程 中 的 
全 局 标志 位 变量 
QUIT 优雅 地 关闭 整个 服务 
TERM 或 者 INT 强制 关闭 整个 服务 
USRI1 重新 打开 服务 中 的 所 有 文件 


所 有 子 进程 不 再 接受 处 理 新 的 连接 ， 实 际 相 汝 于 对 所 有 的 子 进 程 
WINCH ngx noaccept A es 人 0 et 
发 送 QUIT 信号 量 


USR2 平滑 升级 到 新 版 本 的 Nginx 程序 
HUP 重读 配置 文件 并 使 服务 对 新 配置 项 生效 


ed i 有 子 进 程 意 可 束 a 这 了 需 要 监控 所 有 的 子 进 程 ， 也 就 是 ngx_ 
reap_children 方法 所 做 的 工作 


测 
X 


信 号 








表 8-4 列 出 了 master 工 作 流程 中 的 7 个 全 局 标志 位 变量 。 除 此 之 外 ， 
还 有 一 个 标志 位 也 会 用 到 ， 它 仅仅 是 在 master 工 作 流 程 中 作为 标 志 位 使 
用 的 ， 与 信号 无 关 。 





ngx_uint_t ngx_restart; 





在 解释 master 工 作 流 程 前 ， 还 需要 对 master 进 程 管理 子 进程 的 数据 
结构 有 个 初步 了 解 。 下 面 定义 了 ngx_processes 全 局 数组 ， 虽 然 子 进程 中 
也 会 有 ngx_processes 数 组 ， 但 这 个 数组 仅仅 是 给 master 进 程 使 用 的 。 下 
面 看 一 下 ngx_processes 全 局 数组 的 定义 ， 代 码 如 下 。 





XY 定居 


1024 个 元 素 的 


ngx_processes 数 组 ， 也 就 是 最 多 只 能 有 


1024 个 子 进程 


#define NGX_MAX_PROCESSES 1024 
// 当前 操作 的 进程 在 


ngx_processes 数 组 中 的 下 标 


ngx_int_t ngx_process_slot; 
// ngx_processes 数 组 中 有 意义 的 


ngx_process_t 元 素 中 最 大 的 下 标 


ngx_int_t ngx_last_process; 
// 存储 所 有 子 进程 的 数组 





ngx_process_t ngx_processes[NGX MAX PROCESSES]; 





master 进 程 中 所 有 子 进程 相关 的 状态 信息 都 保存 在 ngx_processes 数 
组 中 。 再 来 看 一 下 数组 元 素 的 类 型 ngx_process_t 结 构 体 的 定义 ， 代 码 如 
下 





typedef struct { 
// 进程 


ID 
ngx_pid_t pid; 
// 由 


waitpid 系 统 调用 获取 到 的 进程 状态 


int status,; 
/* 这 是 由 


socketpair 系 统 调用 产生 出 的 用 于 进程 间 通 信 的 
SOCcket 句 柄 ， 这 一 对 
SOCKket 身 杨 可 以 互相 通信 ， 目 前 用 于 
master 父 进程 与 

worker 子 进程 间 的 通信 ， 详 见 

14 .4 节 


*/ 
ngx_socket_t channel[2]; 
// 子 进 程 的 循环 执行 方法 ， 当 父 进程 调用 


ngx_spawn_process 生 成 子 进程 时 使 用 


ngx_spawn_proc_pt proc; 
/* 上 面 的 


ngx_spawn_proc_pt 方 法 中 第 


2 个 参数 需要 传递 


1 个 指针 ， 它 是 可 选 的 。 例 如 ， 


Worker 子 进程 就 不 需要 ， 而 


Cache manage 进 程 就 需要 


ngx_cache_manager_ctx 上 下 文成 员 。 这 时 ， 


data 一 般 与 


ngx_spawn_proc_pt 方 法 中 第 


2 个 参数 是 等 价 的 


*X 
void *data; 
// 进程 名 称 。 操 作 系 统 中 显示 的 进程 名 称 与 


name 相 同 


char *name 
// 标志 位 ， 为 


1 时 表示 在 重新 生成 子 进程 


unsigned respawn:1; 
// 标志 位 ， 为 


1 时 表示 正在 生成 子 进程 


unsigned just_spawn:1; 
// 标志 位 ， 为 


1 时 表示 在 进行 父 、 子 进程 分 离 


unsigned detached:1; 
// 标志 位 ， 为 


1 时 表示 进程 正在 退出 


unsigned exiting:1; 
// 标志 位 ， 为 


1 时 表示 进程 已 经 退出 


unsigned exited:1; 
} ngx_process_t; 





master 进 程 怎样 启动 一 个 子 进程 呢 ? 其 实 很 简单 ，fork 系 统 调用 即 
可 以 完成 。ngx_spawn_process 方 法 封装 了 fork 系 统 调用 ， 并 且 会 从 
ngx_processes 数 组 中 选择 一 个 还 未 使 用 的 ngx_process_t 元 素 存 储 这 个 子 
进程 的 相关 信息 。 如 果 所 有 1024 个 数组 元 素 中 已 经 没有 空余 的 元 素 ， 也 
就 是 说 ， 子 进程 个 数 超过 了 最 大 值 1024， 那 么 将 会 返回 
NGX_INVALID_PID。 因 此 ，ngx_processes 数 组 中 元 素 的 初始 化 将 在 


ngx_spawn_process 方 法 中 进行 。 


下 面 对 局 动 子 进程 的 方法 做 一 个 简单 说 明 ， 它 的 定义 如 下 。 





ngx_pid t ngx_spawn_ process(ngx_cycle t *cycle, ngx_spawn_proc_pt proc, void *data, 








这 里 的 proc 函 数 指 针 束 是 子 进程 中 将 要 执行 的 工作 循环 。 下 面 看 一 
下 ngx_spawn_proc_pt 的 定义 ， 代 码 如 下 。 





typedef void (*ngx_spawn_proc_pt) (ngx_cycle t *cycle, void *data); 


此 ，worker 进 程 的 工作 循环 ngx_worker_process_cycle 方 法 也 是 依 
照 ngx_spawn_proc_pt 来 定义 的 ， 代 码 如 下 。 





static void ngx_worker_process cycle(ngx_cycle t *cycle, void *data); 





cache manage 进 程 或 者 cache loader 进 程 的 工作 循环 
ngX_cache_manager_process_cycle 方 法 也 是 如 此 ， 代 码 如 下 。 





static void ngx_cache manager_process cycle(ngx_ cycle t *cycle, void *data); 








那么 ，ngx_processes 数 组 中 这 些 进程 的 状态 是 怎么 改变 的 呢 ? 依靠 
信号 ! 当 每 个 子 进程 意外 退出 时 ，master 父 进程 会 接收 到 Linux 内 核发 来 
的 CHLD 信 号 ， 而 处 理 信号 的 ngx_signal_handler 方 法 这 时 将 会 做 以 下 处 
理 : 将 sig_reap 标 志 位 置 为 !1， 调 用 ngx_process_get_status 方 法 修改 
ngx_processes 数 组 中 所 有 子 进程 的 状态 (通过 waitpid 系 统 调用 得 到 意外 
结束 的 子 进程 ID， 然 后 遍历 ngx_processes 数 组 找到 该 子 进程 ID 对 应 的 
ngx_process t 结 构 体 ， 将 其 exited 标 志 位 置 为 1) 。 那 么 ， 一 个 子 进程 意 
外 结束 后 ， 如 何 启动 新 的 子 进程 呢 ? 这 可 以 在 图 8-8 所 示 的 master 进 程 的 
工作 循环 中 找到 答案 。 











[ngx_reap 标 志 位 为 1] 





1 监控 子 进程 , 若 所 有 子 进程 


2 已 退出 则 返回 的 live 关 


live 标 志 位 为 0, 同时 ngx_terminate 或 者 ngx_quit 标 志 位 为 
5 商 有 sy iv / ngx_termin ngx_qui / ] 


ERM 信 号 
[ngx terminate 标 志 位 为 1, 强制 关闭 服务 ] 2) 删 除 存储 master 















进程 号 的 pid 文 件 
7) 辣 所 有 了 还 各 发 到 [ngx_terminate 为 0 ] 5 再 用 记 有 模 英 的 
了 exit_ master 方 法 










[ngx_quit 标志 位 为 1， 
优雅 地 关闭 服务 ] 
闭 所 有 [ngx_guit 为 0 ] 
听 端 口 








4) 关 闭 所 有 
监听 端口 
5) 销 毁 内 存 池 


[ngx_reconfigure 为 0] 【3 





8 ) 天 
监 





[ngx_reconfigure 标 志 


9) 重 新 读 取 








配置 文件 ep 
[ngx_restart 标 志 位 为 1] 13) 局 动 
worker 子 进程 








10) 启动 worker 
子 进 程 


11) 启动 cache manage 


12) 向 所 有 子 进程 发 送 
QUIT 信 号 






[ngx_restart 为 0] 







14) 启动 cache manage 
进 


程 





[ngx_reopen 标志 位 为 1 | 





15) 重 新 打 
所 有 文 


开 
文件 


A 


CD 


eopen 为 0 
[ngx_reopen 0] 16) 向 所 有 的 子 进 程 发 这 
言 号 要 求 重新 打开 文件 
[ngx_change _binary 标 志 位 为 1] 
17) 运行 新 的 Nginx 


二 进 制 文件 
[ngx_change_binary 为 0] 


< 


[ngx_noaccept 标志 位 为 1] 











18) 向 所 有 子 进程 发 送 





QUIT 信 号 要 求 关闭 服务 


图 8-8 mastet 进 程 的 工作 循环 





下 面 简要 介绍 一 下 图 8-8 中 列 出 的 流程 。 实 际 上 ， 根 据 以 下 8 个 标志 


位 : ngx_reap、ngx_terminate、ngx_quit、ngx_reconfigure、ngx_restart、 
ngx_reopen、ngx_change_binary、ngx_noaccept， 决 定 执行 不 同 的 分 支流 
程 ， 并 循环 执行 《注意 ， 每 次 一 个 循环 执行 完毕 后 进程 会 被 挂 起 ， 直 到 
有 新 的 信号 才 会 激活 继续 执行 ) 。 


1) 如 果 ngx_reap 标 志 位 为 0， 则 继续 向 下 执行 第 2 步 ， 如 果 ngx_reap 
标志 位 为 1， 则 表示 需要 监控 所 有 的 子 进程 ， 同 时 调用 表 8-2 中 的 
ngx_reap_children 方 法 来 管理 子 进 程 。 这 时 ，ngx_reap_children 方 法 将 会 
授 历 ngx_processes 数 组 ， 检 查 每 个 子 进 程 的 状态 ， 对 于 非 正常 退出 的 子 
进程 会 重新 拉 起 。 最 后 ，ngx_processes 方 法 会 返回 一 个 ]ive 标 志 位 ， 如 
果 所 有 的 子 进程 都 已 经 正常 退出 ， 那 么 live 将 为 0， 除 此 之 外 ，live 会 为 
1。 














2) 当 ]ive 标 志 位 为 0( 所 有 子 进程 已 经 退出 ) 、ngx_terminate 标 志 
位 为 1 或 者 ngx_quit 标 志 位 为 1 时 ， 都 将 调用 ngx_master_process_exit 方 法 
开始 退出 master 进 程 ， 人 否则 继续 癌 下 执行 第 6 步 。 在 
ngX_master_process_exit 方 法 中 ， 首 先 会 删除 存储 进程 号 的 pid 文 件 。 


3) 继续 之 前 的 ngx_master_process_exit 方 法 ， 调 用 所 有 模块 的 


exit_ master 方 法 。 


4) 调用 ngx_close_listening_sockets 方 法 关闭 进程 中 打开 的 监听 端 


5) 销毁 内 存 池 ， 退 出 master 进 程 。 


6) 如 果 ngx_terminate 标 志 位 为 1， 则 癌 所 有 子 进 程 用 送信 号 
TERM， 通 知 子 进程 强制 退出 进程 ， 接 下 来 直接 跳 到 第 1 步 并 挂 起 进 
程 ， 等 竺 信号 激活 进程 。 如 果 ngx_terminate 标 志 位 为 0， 则 继续 执行 第 7 


I 
Yo 


~ 





7) 如 果 ngx_qduit 标 志 位 为 0， 跳 到 第 9 步 ， 否 则 表示 需要 优雅 地 退出 
服务 ， 这 时 会 同 所 有 子 进程 发 送 QUIT 信 号 ， 通 知 它们 退出 进程 。 








8) 继续 ngx_quit 为 1 的 分 文 流程。 关闭 所 有 的 监听 端口 ， 接 下 来 直 
接 跳 到 第 1 步 并 挂 起 master 进 程 ， 等 待 信号 激活 进程 。 





9) 如 果 ngx_reconfigure 标 志 位 为 0， 则 跳 到 第 13 步 检查 ngx_restart 标 
志 位 。 如 果 ngx_reconfigure 为 1， 则 表示 需要 重新 读 取 配置 文件 。Nginx 
不 会 再 让 原先 的 worker 等 子 进程 再 重新 读 取 配 置 文件 ， 它 的 策略 是 重新 
初始 化 ngx_cycle_t 结 构 体 ， 用 它 来 读 取 新 的 配置 文件 ， 再 拉 起 新 的 
worker 进 程 ， 销 毁 旧 的 worker 进 程 。 本 步 中 将 会 调用 ngx_init_ cycle 方法 
重新 初始 化 ngx_cycle_t 结 构 体 。 


10) 接 第 9 步 ， 调 用 ngx_start_worker_processes 方 法 再 拉 起 一 批 
worker 进 程 ， 这 些 worker 进 程 将 使 用 新 ngx_cycle_t 结 构 体 。 


11) 接 第 10 步 ， 调 用 ngx_start_cache_manager_processes 方 法 ， 按 照 


绥 存 模块 的 加 载 情况 决定 是 否 拉 起 cache manage 或 者 cache loader 进 程 。 
在 这 两 个 方法 调用 后 ， 肯 定 是 存在 子 进程 了 ， 这 时 会 把 live 标 志 位 置 为 


1 第 2 步 中 曾 用 到 此 标志 )。 





12) 接 第 11 步 ， 问 原先 的 〈 并 非 刚 刚 拉 起 的 ) 所 有 子 进程 发 送 
QUIT 信 号 ， 要 求 它 们 优雅 地 退出 目 己 的 进程 。 





13) 检查 ngx_restart 标 志 位 ， 如 果 为 0， 则 继续 第 15 步 ， 检 查 
ngx_reopen 标 志 位 。 如 果 ngx_restart 为 1， 则 调用 
ngx_start_worker_processes 方 法 拉 起 worker 进 程 ， 同 时 将 ngx_restart 置 为 
0。 





14) 接 13 步 ， 调 用 ngx_start_cache_manager_processes 方 法 根据 缓存 
模块 的 情况 选择 是 否 启 动 cache manage 进 程 或 者 cache loader 进 程 ， 同 时 


将 live 标 志 位 置 为 1。 





15) 检查 ngx_reopen 标 志 位 ， 如 果 为 0， 则 继续 第 17 步 ， 检 查 
ngx_change_binary 标 志 位 。 如 果 ngx_reopen 为 1， 则 调用 ngx_reopen_files 
方法 重新 打开 所 有 文件 ， 同 时 将 ngx_reopen 标 志 位 置 为 0。 





16) 问 所 有 子 进 程 发 送 USR1 信 号 ， 要 求 子 进程 都 得 重新 打开 所 有 
| 


17) 检查 ngx_change_binary 标 志 位 ， 如 果 ngx_change_binary 为 1， 











则 表示 需要 平滑 升级 Nginx， 这 时 将 调用 ngx_exec_new_binary 方 法 用 新 
的 子 进程 启动 新 版 本 的 Nginx 程 序 ， 同 时 将 ngx_change_binary 标 志 位 置 
为 0。 


18) 检查 ngx_noaccept 标 志 位 ， 如 果 ngx_noaccept 为 0， 则 继续 第 1 步 
进行 下 一 个 循环 ， 如 果 ngx_noaccept 为 1， 则 同 所 有 的 子 进 程 友 送 QUIT 
信号 ， 要 求 它 们 优雅 地 关闭 服务 ， 同 时 将 ngx_noaccept 置 为 0， 并 将 
ngx_noaccepting 置 为 1， 表 示 正 在 俘 止 接受 新 的 连接 。 











注意 ， 在 以 上 18 个 步骤 组 成 的 循环 中 ， 并 不 是 不 停 地 在 循环 执行 以 
上 步骤 ， 而 是 会 通过 sigsuspend 调 用 使 master 进 程 休 眠 ， 等 待 master 进 程 
收 到 信号 后 激活 master 进 程 继续 由 上 面 的 第 1 步 执 行 循环 。 


8.7 ngx_pool t 内 存 池 


在 说 明 其 设计 前 先 来 看 看 与 ngx_pool_t 内 存 池 相关 的 15 个 方法 ， 如 
表 8-5 所 示 。 


表 8-5 内 存 池 操作 方法 


方法 类 型 

创建 内 存 池 ， 注 意 它 的 size 参数 并 不 等 同 于 可 分 配 空间 ， 
它 同时 包含 了 管理 结构 的 大 小 ， 这 意味 着 : size 绝 不 能 小 于 
sizeof ( ngx_pool t)， 和 否则 就 会 有 内 存 越界 错误 。 通 第 ， 可 以 
设 size 为 NGX _ DEFAULT POOL SIZE， 该 安 目 前 为 16KB， 
不 用 担心 16KB 会 不 够 用 ， 当 这 第 一 个 16KB 用 完 时 ， 会 自动 
再 分 配 16KB 内 存 的 

销毁 内 存 池 ， 它 同时 会 把 通过 该 pool 分 配 出 的 内 存 释 放 ， 
ngx_destroy_pool 而 且 ， 还 会 执行 通过 ngx_pool_cleanup_add 方法 添加 的 各 类 
资源 清理 方法 

重 置 内 存 池 ， 即 将 内 存 池 中 的 原 有 内 存 释 放 后 继续 使 用 
ngx_ reset_pool 这 个 方法 的 实现 是 , 会 把 大 块 内 存 释放 给 操作 系统 ， 而 小 块 
内 存 则 在 不 释放 的 情况 下 复 用 


ngx create_ pool 


内 存 池 操作 





( 续 ) 


方法 类 型 意义 


分 配 地 址 对 齐 的 内 存 。 按 总 线 长 度 (例如 sizeof (unsigned 





ngx_palloc long)) 对 齐 地 址 后 ， 可 以 减少 CPU 读 取 内 存 的 次 数 ， 当 然 代 
价 是 有 一 些 内 存 浪费 
ngx_pnalloc 分 配 内 存 时 不 进行 地 址 对 齐 
分 配 出 地 址 对 齐 的 内 存 后 ， 再 调用 memset 将 这 些 内 存 全 部 
ngx_pcalloc 清 0 
基于 内 存 池 的 二 a 
分 配 、 释 放 内 存 按 参 数 alignment 进行 地 址 对 齐 来 分 配 内 存 。 注 意 ， 这 样 分 
sy , 配 出 的 内 存 不 管 申请 的 size 有 多 小 ， 都 是 不 会 使 用 小 块 内 在 
操作 ngx_pmemalign 


池 的 ， 它 会 从 进程 的 堆 中 分 配 内 存 ， 并 挂 在 大 块 内 存 组 成 的 
large 单 链表 中 

提前 释放 大 块 内 存 。 它 的 效率 不 高 ， 其 实现 是 遍历 large 链 
表 ， 寻 找 ngx_pool large t 的 alloc 成 员 等 于 待 释放 地 址 ， 技 
到 后 释放 内 存 给 操作 系统 ， 将 ngx_pool large t 移 出 链表 并 
删除 

添加 一 个 需要 在 内 存 池 释放 时 同步 释放 的 资源 。 该 方法 会 
返回 一 个 ngx_pool_cleanup t 结构 体 ， 而 我 们 得 到 后 需要 设置 
ngx_pool_cleanup 的 handler 成 员 为 释放 资源 时 执行 的 方法 。 
ngx_pool cleanup add ngx_pool_cleanup_add 有 一 个 参数 size， 当 它 不 为 0 时 ,会 分 
配 size 大 小 的 内 存 ， 并 将 ngx_pool_cleanup t 的 data 成 员 指 
向 该 内 存 ， 这 样 可 以 利用 这 段 内 存 传递 参数 ， 供 释放 资源 的 


ngx_pfree 


随 荐 内 存 池 释 方法 使 用 。 当 size 为 0 时 ，data 将 为 NULL 
放 同 步 释 放 资 源 在 内 存 池 释放 前 ， 如 果 需 要 提前 关闭 文件 (当然 是 调用 过 
的 操作 ngx_pool_cleanup_add 添加 的 文件 ， 同 时 ngx_pool_cleanup_ 


ngx pool run cleanup file a 
RO Ee t 的 handler 成 员 被 设 为 ngx pool cleanup file)， 则 调用 该 


方法 


以 关闭 文件 来 释放 资源 的 方法 ， 可 以 设置 到 ngx_pool_ 
ngx_pool_cleanup_file 
cleanup t 的 handler 成 员 
以 删除 文件 来 释放 资源 的 方法 ， 可 以 设置 到 ngx_pool_ 
ngx_pool delete_file 
cleanup t 的 handler 成 员 


从 操作 系统 中 分 配 内 存 
站 存 训 邱 关 | nex ealoe | 从 操作 系统 中 分 号 出 内 在， 再 调用 memset 把 内 存 清 0 
的 分 配 、 释 放 操作 | ER 
笠 放 内 存 到 操作 系统 





Nginx 已 经 提供 封装 了 malloc、free 的 ngx_alloc、ngx_free 方 法 ， 为 
什么 还 需要 一 个 挺 复杂 的 内 存 池 呢 ? 对 于 没有 垃圾 回收 机 制 的 C 语 言 编 
写 的 应 用 来 说 ， 最 容易 犯 的 错 就 是 内 存 泄露 。 当 分 配 内 存 与 释放 内 存 的 


馆 辑 相距 遥远 时 ， 还 很 容易 发 生 同 一 块 内 存 被 释放 两 次 。 内 存 池 就 是 为 
了 降低 程序 员 犯 错 几 率 的 : 模块 开发 者 只 需要 关心 内 存 的 分 配 ， 而 释放 
则 交 由 内 存 池 来 负责 。 





那么 ，ngx_pool_t 内 存 池 什么 时 候 会 释放 内 存 呢 ? 一 般 地 ， 内 存 池 
销毁 时 才 会 将 内 存 释 放 回 操作 系统 (例外 就 是 表 8-5 中 的 ngx_pfree 方 
法 ) 。 在 一 个 内 存 池 上 ， 可 以 任意 次 的 申请 内 存 ， 不 用 释放 它们 ， 唯 一 
要 做 的 就 是 记得 销毁 内 存 池 。 这 一 策略 在 降低 程序 员 们 出 错 概率 的 同 
时 ， 引 入 了 男 一 问题 ， 如 果 这 个 内 存 池 的 生命 周期 很 长 ， 而 每 一 块 内 存 
的 生命 周期 很 得， 早期 申请 的 内 存 会 一 直 无 谓 地 占用 着 珍贵 的 内 存 资 
源 ， 这 不 是 造成 严重 的 内 存 浪 费 吗 ? 比如 生成 内 存 池 后 1 天 后 销毁 它 ， 
这 1 天 中 每 秒 申请 1K 的 内 存 ， 而 申请 到 的 每 块 内 存在 这 一 秒 中 就 已 经 使 
用 完毕 ， 这 样 1 天 结束 时 这 个 内 存 池 已 经 占用 了 86MB 的 内 存 ! 没 错 ， 如 
果 内 存 与 内 存 池 的 生命 周期 是 如 此 差异 ， 那 么 这 个 问题 是 存在 的 。 所 
以 ， 一 般 性 的 应 用 中 没有 见 过 这 样 的 内 存 池 设计 。 但 是 ngx_pool t 内 存 
池 却 可 以 应 用 在 Nginx 上 ， 这 是 因为 Nginx 是 一 个 很 纯粹 的 web 服 务 器 ， 
与 客户 端的 每 一 个 TCP 连 接 有 明确 的 生命 周期 ，TCP 连 接 上 的 每 一 个 
HTTP 请 求 有 非常 短暂 的 生命 周期 ， 如 果 每 个 请 求 、 连 接 都 有 各 目的 内 
存 池 ， 而 模块 开发 者 们 评估 待 申请 内 存 的 使 用 周期 ， 如 果 隶 属于 一 个 
HTTP 请 求 ， 则 在 请 求 的 内 存 池 上 分 配 内 存 ， 如 果 录 属于 一 个 连接 ， 则 
在 连接 的 内 存 池上 分 配 内 存 ， 如 果 一 直 伴 随 着 模块 ， 则 可 以 在 
ngx_conf t 的 内 存 池上 分 配 内 存 。 似 乎 我 们 得 到 了 不 用 释放 内 存 的 好 




















处 ， 却 增加 了 关心 内 存 生命 周期 的 额外 工作 ? 事实 不 是 这 样 的 ， 绝 大 多 
数 模 块 都 在 单纯 的 处 理 请 求 ， 只 需要 使 用 ngx_http_request_t 中 的 内 存 池 
印 可 。 


ngx_pool {t 内 存 池 的 设计 上 还 考虑 到 了 小 块 内 存 的 频 楷 分 配 在 效率 
上 有 提升 空间 ， 以 及 内 存 碎 上 请 还 可 以 再 减少 些 。 在 讨论 其 实现 前 ， 先 定 
义 什 么 叫 小 块 内 存 ，NGX_MAX_ALLOC_FROM_POOL 宏 是 一 个 很 重 
要 的 标准 : 





#define NGX MAX ALLOC FROM POOL (ngx_pagesize - 1) 








可 见 ， 在 X86 架构 上 就 是 4095 字 节 。 通 常 ， 小 于 等 于 
NGX_MAX_ALLOC_FROM_POOL 就 意味 着 小 块 内 存 。 这 并 不 是 绝对 
的 ， 当 调用 ngx_create_pool 创 建 内 存 池 时 ， 如 果 传 递 的 size 参 数 小 于 
NGX_MAX_ALLOC_FROM_POOL+sizeofngx_pool D， 则 对 于 这 个 内 
存 池 来 说 ，size-sizeof(ngx_pool_b 字 闻 就 是 小 块 内 存 的 标准 。 大 块 内 存 
与 小 块 内 存 的 处 理 很 不 一 样 ， 看 看 ngx_pool_t 的 定义 就 知道 了 : 





typedef struct ngx_pool_s ngx_pool_t; 
Struct ngx_pool s { 
// 描述 小 块 内 存 池 。 当 分 配 小 块 内 存 时 ， 剩 余 的 预 分 配 空间 不 足 时 ， 会 再 分 配 


1 


ngx_pool_t, 


// 它们 会 通过 


d 中 的 


next 成 员 构 成 单 链表 


ngx_pool data t d; 
// 评估 申请 内 存 属于 小 \ 块 还 是 大 块 的 标准 


size_t max; 


// 多 个 小 块 内 存 池 构成 链表 时 ， 


current 指向 分 配 内 存 时 遍历 的 第 


1 个 小 块 内 存 池 


ngx_pool t *current; 
// 用 于 


ngx_output_chain, 与 内 存 池 关 系 不 大 ， 略 过 


ngx_chain_t *chain; 
// 大 块 内存 都 直接 从 进程 的 堆 中 分 配 ， 为 了 能 够 在 销毁 内 存 池 时 同时 释放 大 块 内 存 ， 


// 就 把 每 一 次 分 配 的 大 块 内 存 通 


ngx_pool_large _t 组 成 单 链 表 挂 在 


Jarge 成 员 上 


ngx_pool_Jarge 上 *]arge 
// 所 有 待 清理 资源 (例如 需要 关闭 或 者 删除 的 文件 ) 以 


ngx_pool_cleanup 七 对 象 构 成 单 链 表 ， 


// 挂 在 


cleanup 成 员 上 


ngx_pool_ cleanup_t *cleanup; 
// 内 存 池 执 行 中 输出 日 志 的 对 象 


ngx_log_t *10g; 
}; 





从 上 面 代 码 的 注释 中 可 知 ， 当 申请 的 内 存 算 是 大 块 内 存 时 (大 于 
ngx_pool_t 的 max 成 员 ) ， 是 直接 调用 ngx_alloc 从 进程 的 堆 中 分 配 的 ， 
同时 会 再 分 配 一 个 ngx_pool_large_t 结 构 体 挂 在 large 链 表 中 ， 其 定义 如 
革 











typedef struct ngx_pool large s ngx pool large t; 
struct ngx_pool large s { 
// 所 有 大 块 内 存 通过 


next 指 针 联 在 一 起 


ngx_pool_large_t *next; 
// alloc 指 向 


ngx_alloc 分 配 出 的 大 块 内 存 。 调 用 


ngx_pfree 后 


alloc 可 能 是 


NULL 
void *alloc; 








对 于 非常 大 的 内 存 ， 如 果 它 的 生命 周期 远 远 的 短 于 所 属 的 内 存 池 ， 
那么 在 内 存 池 销毁 前 提前 的 释放 它 就 变 得 有 意义 了 。 而 ngx_pfree 方 法 就 
是 提前 释放 大 块 内 存 的 ， 需 要 注意 ， 它 的 实现 是 授 历 large 链 表 ， 找 到 











alloc 等 于 待 释放 地 址 的 ngx_pool_large_t 后 ， 调 用 ngx_free 释 放大 块 内 
存 ， 但 不 释放 ngx_pool_large_t 结 构 体 ， 而 是 把 alloc 置 为 NULL。 如 此 实 
现 的 意义 在 于 : 下 次 分 配 大 块 内 存 时 ， 会 期 望 复 用 这 个 ngx_pool_large_t 

结构 体 。 从 这 里 可 以 想见 ， 如 果 large 链 表 中 的 元 素 很 多 ， 那 么 ngx_free 
的 遍历 损耗 的 性 能 是 不 小 的 ， 如 果 不 能 确定 内 存 确实 非常 大 ， 最 好 不 要 
调用 ngx_pfree。 





再 来 看 看 小 块 内 存 ， 通 过 从 进程 的 堆 中 预 分 配 更 多 的 内 存 
Cngx_create_pool 的 Size 参数 决定 预 分 配 大 小 ) ， 而 后 直接 使 用 这 甘 内 
存 的 一 部 分 作为 小 块 内 存 返 回 给 申请 者 ， 以 此 实现 减少 碎片 和 调用 
malloc 的 次 数 。 它 们 是 放 在 成 员 d 中 维护 管理 的 ， 看 看 ngx_pool_data_t 是 
如 何 定义 的 : 








typedef struct { 
// 指向 未 分 配 的 空闲 内 存 的 首 地 址 


u_char *]ast 
// 指向 当前 小 块 内 存 池 的 尾部 


u_char *end; 
// 同属 于 一 个 


p001 的 多 个 小 块 内 存 池 间 ， 通 过 


next 相 连 


ngx_pool_t *next; 
// 每 当 剩余 空间 不 足以 分 配 出 小 块 内 存 时 ， 


failed 成 员 就 会 加 


1。 


failed 成 员 大 于 


4 后 


// ( 


Nginx1.4.4 版 本 ) ， 


ngx_pool_t 的 


cuUrrent 将 移 向 下 一 个 小 块 内 存 池 


ngx_uint_t failed; 
} ngx_pool data t; 





当 内 存 池 预 分 配 的 size 不 足 使 用 时 ， 就 会 再 接着 分 配 一 个 小 块 内 存 
闻 ， 预 分 配 大 小 与 原 内 存 池 相等 ， 且 仍然 使 用 ngx_pool_t 表 示 这 个 纯粹 
的 小 块 内 存 池 ， 用 ngx_pool_data_t 的 next 成 员 相 连 。 这 样 ， 这 个 新 增 的 
ngx_pool_t 结 构 体 中 与 小 块 内 存 无 关 的 其 他 成 员 此 时 是 无 意义 的 ， 例 如 
max 不 会 赋值 、large 链 表 为 空 等 。 








ngx_pool_t 不 只 希望 程序 员 不 用 释放 内 存 ， 而 且 还 能 不 需要 释放 如 
文件 等 资源 。 例 如 第 12 章 介绍 的 upstream 实 现 的 反 向 代理 ， 其 存放 http 
协议 包 体 的 文件 就 希望 它 可 以 随 着 ngx_pool t 内 存 池 的 销毁 被 自动 关闭 
并 删除 掉 。 怎 么 实现 呢 ? 表 8-5 中 的 ngx_pool_cleanup_add 方 法 就 用 来 提 


供 这 一 功能 ， 它 会 返回 ngx_pool_cleanup_t 结 构 体 ， 其 定义 如 下 所 示 : 





// 实现 这 个 回调 方法 时 ， 


data 参 数 将 是 


ngx_pool_cleanup_pt 的 


data 成 . 员 


typedef void (*ngx_pool cleanup_pt)(void *data); 
typedef struct ngx_ pool cleanup_s ngx_pool cleanup_t; 
struct ngx_pool cleanup_s { 

// handler 初 始 为 


NULL， 需 要 设置 为 清理 方法 


ngx_pool_cleanup_pt handler; 
// ngx_pool _cleanup_add 方 法 的 


size>0 时 


data 不 为 


NULL， 此 时 可 改写 


data 指 向 的 内 存 ， 


// 用 于 为 


handler 指 向 的 方法 传递 必要 的 参数 


void *data; 
// 由 


ngx_pool_cleanup_add 方 法 设置 


next 成 员 ， 用 于 将 当前 


ngx_pool_ cleanup_t 
// 添加 到 


ngx_pool_t 的 


cleanup 链 表 中 


ngx_pool_ cleanup_t *next; 





3.8.2 节 就 是 一 个 很 好 的 资源 释放 例子 ， 当 我 们 将 handler 设 为 表 8-5 
中 的 ngx_pool_delete_file 方 法 时 可 以 删除 文件 。 


图 8-9 完 整地 展示 了 ngx_pool {t 内 存 池 中 小 块 内 存 、 大 块 内 存 、 资 源 
清理 链表 间 的 关系 。 图 中 ， 内 存 池 预 分 配 的 小 块 内 存 区 域 剩余 空 闲 空间 
不 足以 分 配 某 些 内 存 ， 导 致 又 分 配 出 2 个 小 块 内 存 池 。 其 中 原 内 存 池 的 
failed 成 员 已 经 大 于 4， 所 以 current 指 向 了 第 2 个 小 块 内 存 池 ， 这 样 再 次 分 
配 小 块 内 存 时 将 会 急 略 第 1 个 小 块 内 存 池 。〔 从 这 里 可 以 看 到 ， 分配 内 
存 的 行为 可 能 导致 每 个 内 存 池 最 大 NGX_MAX_ALLOC_FROM_POOL-1 
字 节 的 内 存 浪费 。) 图 中 共 分 配 3 个 大 块 内 存 ， 其 中 第 2 个 大 块 内 存 调用 
过 ngx_pfree 方 法 释放 了 。 图 中 还 挂 载 了 两 个 资源 清理 方法 。 











图 8-10 以 分 配 地 址 对 齐 的 内 存 为 例 ， 列 出 了 主要 步骤 的 流程 图 ， 可 
以 给 读者 朋友 们 更 直观 的 印象 ， 下 面 详细 解释 各 步骤 : 


1) 将 申请 的 内 存 大 小 size 与 ngx_pool t 的 max 成 员 比 较 ， 以 决定 申 
请 的 是 小 块 内 存 还 是 大 块 内 存 。 如 果 size<=max， 则 继续 执行 第 2 步 开始 
分 配 小 块 内 存 ， 盏 则 ， 跳 到 第 10 步 分 配 大 块 内 存 。 





2) 取 到 ngx_pool_t 的 current 指 针 ， 它 表示 应 当 首先 尝试 从 这 个 小 块 
内 存 池 里 分 配 ， 因 为 current 之 前 的 pool 已 经 屡次 分 配 失败 〈 大 于 4 次 ) ， 
其 剩余 的 空间 多 半 无 法 满足 size。 这 当然 是 一 种 存在 浪费 的 预 估 ， 但 性 
能 不 坏 。 
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图 8-9 ”ngx_pool_t 资 源 池 示 意图 


3) 从 当前 小 块 内 存 池 的 ngx_pool_data_t 的 last 指 针 入 手 ， 先 调用 
ngx_align_ptr 找 到 ]ast 后 最 近 的 对 齐 地 址 。 (可 参考 第 16 章 的 slab 共 享 内 
存 ， 那 里 处 处 需要 地 址 对 齐 。) 





#define ngx_align_ptr(p, a) \ 

(u_char *) (((uintptr_t) (p) + ((uintptr_t) a - 1)) & ~((uintptr_t) a - 1)) 
#define NGX_ALIGNMENT sizeof(unsigned long) 
ngx_pool t *p = … 


// 取得 
]ast 的 


NGX_ALIGNMENT 字 节 对 齐 地 址 


u_char* m = ngx_align_ptr(p->d. Last，NGX_ALIGNMENT ) ， 








4) 比较 对 齐 地 址 与 hgx_pool_data_t 的 end 指 针 间 是 否 可 以 容纳 size 
字 节 。 如 果 end-m>=size， 那 么 继续 执行 第 5 步 准备 返回 地 址 m;， 否则， 
再 检查 ngx_pool_data_t 的 next 指 针 是 人 否 为 NULL， 如 果 是 空 指针 ， 那 么 跳 
到 第 6 步 准备 再 申请 新 的 小 块 内 存 池 ， 不 为 空 则 跳 到 第 3 步 继续 遍 历 小 块 
内 存 池 构 成 的 链表 。 


5) 移 将 ngx_pool_data_t 的 last 指 针 置 为 下 次 空闲 内 存 的 首 地 址 ， 例 
如 : 





p->d.last = m + size; 





再 返回 地 址 m， 分 配 内 存 流程 结束 。 


6) 分 配 一 个 大 小 与 上 一 个 ngx_poolL_t 一 致 的 内 存 池 专用 于 小 块 内 存 
的 分 配 。 内 存 池 大 小 获取 很 简单 ， 如 下 : 


(size_t) ( pool->d.end - (u_char *) pool) 





7) 将 新 内 存 池 的 空闲 地 址 的 首 地 址 对 齐 ， 作 为 返回 给 申请 的 内 
存 ， 再 设 last 到 空闲 内 存 的 首 地 址 。 


8) 从 current 指 同 的 小 块 内 存 池 开始 遍历 到 当前 的 新 内 存 池 ， 依 次 
将 各 failed 成 员 加 1， 并 把 current 指 回首 个 failed<=4 的 小 块 内 存 池 ， 用 于 
下 一 次 的 小 块 内 存 分 配 。 


9) 返回 第 7 步 对 齐 的 地 址 ， 分 配 流 程 结束 。 
10) 调用 ngx_alloc 方 法 从 进程 的 堆 内 存 中 分 配 size 大 小 的 内 存 。 


11) 遍历 ngx_pool_t 的 large 链 表 ， 看 看 有 没有 ngx_pool_large_t 的 
alloc 成 员 值 为 NULL (这 个 alloc 指 同 的 大 块 内 存 执行 过 ngx_pfree 方 
法 ) 。 如 果 找 到 了 这 个 ngx_pool_large_t， 继 续 执 行 第 12 步 ， 否 则 ， 跳 到 
第 13 步 执行 。 需 要 注意 的 是 ， 为 了 防止 large 链 表 过 大 ， 遍 历次 数 是 有 限 
制 的 ， 例 如 最 多 4 次 还 未 找到 alloc==NULL 的 元 素 ， 也 会 跳出 这 个 遍历 


循环 执行 第 13 步 。 








12) 把 ngx_pool_large t 的 alloc 成 员 置 为 第 10 步 分 配 的 内 存 地 址 ， 返 
回 地 址 ， 分 配 流程 结束 。 


13) 从 内 存 池 中 分 配 出 ngx_pool_large_t 结 构 体 ，alloc 成 员 置 为 第 10 
步 分 配 的 内 存 地 址 ， 将 ngx_pool_large_t 添 加 到 ngx_pool_t 的 large 链 表 首 
部 ， 返 回 地 址 ， 分 配 流 程 结 束 。 


1 ) 将 分 配 大 小 size 与 ngx_pool_t 的 max 成 员 比 较 





[size<=max] 人 


2 ) 从 current 成 员 指 向 的 ngx_pool_t 开 始 遍 历 pool 链 表 


3 ) 从 当前 ngx_pool_data_t 的 last 指 针 找到 对 齐 地 址 [eesmax] 





4 ) 比较 新 地 址 与 end 之 前 的 空间 大 小 是 否 可 容纳 size 









[找到 一 个 pool 可 以 分 出 size 地 址 ] 


[遍历 ] <> 


[链表 中 的 所 有 pool 都 无 法 分 出 size 内 存 ] 


5 ) 设 last 为 对 齐 地 址 加 上 size， 返 回 对 齐 地 址 


6 ) 分 配 新 的 ngx_pool_t， 大 小 与 第 1 个 pool 一 致 





7 ) 对 齐 空闲 内 存 首 地 址 ， 重 置 last 指 针 





10 ) 分 配 一 块 size 大 小 的 内 存 








8 ) 检查 各 pool 的 failed 次 数 ， 重 置 current 指 针 
11 ) 遍历 pool 的 large 链 表 ， 找 出 alloc=NULL 的 指针 


9 ) 返 回 新 pool 分 配 出 的 对 齐 内 存 地 址 





[来 挨 到 或 遍历 
[找到 alloc 值 为 NULL 的 成 员 ] ”个 数 达 到 上 限 ] 


® 12 ) 将 刚 分 配 内 存 赋 给 alloc， 并 返回 地 址 





13 ) 新 分 配 ngx_pool_large_t 结 构 赋 值 后 挂 在 large 链 表 上 ， 返 回 地 址 





图 8-10 分配 地 址 对 齐 内 存 的 流程 图 


8.8 ”小结 





本 章 主要 理 清 了 Nginx 的 设计 思路 ， 知 道 它 是 如 何 达到 高 性 能 、 高 
可 靠 性 、 高 可 伸缩 性 、 高 可 修改 性 等 要 求 的 。 在 此 基础 上 ， 我 们 以 
ngx_cycle_t 数 据 结构 为 核心 ， 介 绍 了 Nginx 框 架 如 何 启动 、 初 始 化 、 加 
载 各 Nginx 模 块 的 代码 ， 以 及 master 进 程 、worker 进 程 如 何在 工作 循环 中 
运行 。 对 于 worker 进 程 来 说 ， 它 的 工作 流程 更 多 地 体现 在 具体 的 模块 
上 。 例 如 ， 对 于 HTTP 请 求 来 说 ，worker 进 程 大 都 是 由 HTTP 模 块 所 占用 
的 ， 特 别 是 8.5 节 中 提 到 的 ngx_process_events_and_timers 方 法 ， 这 是 第 9 
章 中 事件 模块 将 要 讲述 的 内 容 ， 因 此 ， 对 于 worker 进 程 的 工作 循环 ， 本 
章 并 没有 做 详细 的 说 明 。 对 于 master 进 程 ，8.6 节 内 容 基 本 上 涉及 了 它 在 
工作 循环 中 执行 的 所 有 流程 。 而 对 于 cache manage 和 cache loader 进 程 ， 
它们 是 与 文件 缓存 模块 密切 相关 的 ， 在 不 使 用 文件 缓存 时 ， 这 两 个 进程 
也 不 会 启动 ， 它 们 与 框架 代码 没有 多 少 关 联 ， 本 章 只 是 进行 了 简单 说 
明 。 





ngx_pool { 内 存 池 是 一 个 很 基础 的 设计 ， 本 章 通 过 分 析 其 实现 可 以 
章 


帮助 读者 朋友 们 正确 地 使 用 ngx_pool_t 内 存 池 ， 方 便 阅 读 后 续 章节 。 


通过 阅读 本 章 的 内 容 ， 读 者 应 该 对 Nginx 的 设计 结构 有 了 大 致 的 了 
解 ， 这 样 在 修改 Nginx 的 源码 或 者 开发 一 些 开 币 强 大 且 深 入 的 Nginx 模 块 


时 惑 可 以 得 心 应 手 了 ， 因 为 只 有 在 不 违反 Nginx 本 身 设 计 原 则 的 前 提 下 
才 会 保留 8.2 节 中 所 述 的 优点 。 同 时 ， 本 章 内 容 是 后 续 章 节 的 基础 ， 在 
了 解 事件 模块 、HTTP 模 块 、mail 模 块 前 ， 必 须 对 Nginx 整 个 的 模块 分 
布 、 事 件 驱 动 、 请 求 的 多 阶段 划分 等 特点 有 清晰 的 认识 ， 这 样 在 阅读 后 
续 章 市 时 可 以 做 到 事半功倍 。 


第 9 章 ”事件 模块 


在 上 文中 提 到 ，Nginx 是 一 个 事件 驱动 架构 的 web 服务 器 ， 本 章 将 
全 面 探讨 Nginx 的 事件 驱动 机 制 是 如 何 工作 的 。ngx_event_t 事 件 和 
ngx_connection_t 连 接 是 处 理 TCP 连 接 的 基础 数据 结构 ， 在 对 它们 有 了 基 
本 了 解 后， 在 9.4 节 将 首先 探讨 核心 模块 ngx_events_module， 它 定义 了 
一 种 新 的 模块 类 型 一 事件 模块 ， 而 在 9.5 节 将 开始 说 明 第 1 个 事件 模块 
ngx_event_core_module， 它 的 职责 更 多 地 体现 在 如 何 管理 当前 正在 使 用 
的 事件 驱动 模式 。 例 如 ， 在 Nginx 启 动 时 决定 到 底 是 基于 select 还 是 epoll 
来 监控 网 络 事件 。 








epol 是 目前 Linux 操 作 系 统 上 最 强大 的 事件 管理 机 制 ， 本 书 描述 的 
场景 都 是 使 用 epoll 来 驱动 事件 的 处 理 ， 在 9.6 节 中 ， 首 先 会 深入 到 Linux 
内 核 ， 研 究 epoll 的 实现 原理 和 使 用 方法 ， 以 此 明确 epoll 的 高 并 发 是 怎么 
来 的 ， 以 及 怎样 使 用 epol 才 能 发 挥 它 的 最 大 性 能 。 接 着 ， 就 到 了 
ngx_epoll module 模 块 “ 亮 相 ” 的 时 候 了 ， 这 里 可 以 看 到 一 个 实际 的 事件 
驱动 模块 是 如 何 实现 声明 过 的 事件 抽象 接口 的 〈 见 9.1 节 ) ， 同 时 这 个 
模块 也 是 高 效 使 用 epoll 的 较 好 的 例子 。 例 如 ， 在 使 用 epoll 时 ， 非 常 容易 
遇 到 过 期 事件 的 处 理 问题 ，Nginx 就 使 用 了 一 个 巧妙 的 、 成 本 低廉 的 方 
法 完美 地 解决 了 这 个 问题 ， 稍 后 读者 将 会 看 到 这 个 小 技巧 。 














Nginx 的 定时 器 事件 是 由 第 7 章 中 谈 到 的 红 黑 树 实 现 的 ， 它 也 由 epoll 


等 事件 模块 触及 ， 在 9.7 节 中 ， 该 者 将 看 到 Nginx 如 何 实现 独立 的 定时 天 


功能 。 


在 9.8 节 中 ， 我 们 开始 综合 性 地 介绍 事件 处 理 框 架 ， 这 里 将 会 使 用 
到 9.1 节 ~9.7 节 中 的 所 有 知识 。 这 一 节 将 说 明 核 心 的 
ngx_process_events_and_timers 方 法 处 理 网 络 事 件 、 定 时 器 事件 、post 事 
件 的 完整 流程 ， 同 时 读者 会 看 到 Nginx 是 如 何 解 决 多 个 worker 子 进程 监 
听 同 一 端口 引起 的 “ 惊 群 ?现象 的 ， 以 及 如 何 均衡 多 个 worker 子 进程 上 处 
理 的 连接 数 。 


室 无 疑问 ，Linux 内 核 提 供 的 文件 异步 1O 是 不 同 于 glibc 库 实现 的 多 
线程 伪 异 步 JO 的 ， 它 充分 利用 了 在 Linux 内 核 中 CPU 与 IO 设备 独立 工作 
的 特性 ， 使 得 进程 在 提交 文件 异步 IO 操作 后 可 以 占用 CPU 做 其 他 工 
作 。 在 9.9 节 中 ， 将 会 讨论 这 种 高 效 读 取 磁 盘 的 机 制 ， 在 简单 说 明 它 的 
使 用 方式 后 ， 读 者 还 可 以 看 到 文件 异步 WO 是 如 何 集 成 到 
ngx_epoll_module 模 块 中 与 epoll 一 起 工作 的 。 





9.1 事件 处 理 框架 概述 


事件 处 理 框 染 所 要 解决 的 问题 是 如 何 收集 、 管 理 、 分 发 事件 。 这 里 
所 说 的 事件 ， 主 要 以 网 络 事件 和 定时 器 事件 为 主 ， 而 网 络 事件 中 又 以 
TCP 网 络 事件 为 主 〈Nginx 毕 葛 是 个 web 服 务 器 ) ， 本 章 所 述 的 事件 处 
理 框 架 都 将 围绕 这 两 种 事件 进行 。 





定时 惕 事件 将 在 9.7 节 中 阐述 ， 因 为 它 的 实现 简单 而 且 独 立 ， 同 时 
它 基 于 网 络 事件 的 触发 实现 ， 并 不 涉及 操作 系统 内 核 。 这 里 先 来 了 解 一 
下 Nginx 是 如 何 收集 、 管 理 TCP 网 络 事件 的 。 由 于 网 络 事件 与 网 卡 中 断 
处 理 程序 、 内 核 提供 的 系统 调用 密切 相关 ， 所 以 网 络 事件 的 驱动 既 取 决 
于 不 同 的 操作 系统 平台 ， 在 同一 个 操作 系统 中 也 受制 于 不 同 的 操作 系统 
内 核 版 本 。 这 样 的 话 ，Nginx 文 持 多 少 种 操作 系统 (包括 支持 哪些 版 
本 ) ， 就 必须 提供 多 少 个 事件 驱动 机 制 ， 因 为 基本 上 每 个 操作 系统 提供 
的 事件 驱动 机 制 (通常 事件 驱动 机 制 还 有 个 名 字 ， 叫 做 WO 多 路 复 用 ) 
都 是 不 同 的 。 例 如 ，Linux 内 核 2.6 之 前 的 版 本 或 者 大 部 分 类 UNIX 操 作 系 
统 都 可 以 使 用 poll (ngx_poll_module 模 块 实现 ) 或 者 
select (ngx_select_module 模 块 实现 ) ， 而 Linux 内 核 2.6 之 后 的 版 本 可 以 
使 用 epoll (ngx_epoll_module 模 块 实现 ) ，FreeBSD 上 可 以 使 用 
kqueue (ngx_kqueue_module 模 块 实 现 ) ，Solaris 10 上 可 以 使 用 





eventport (ngx_eventport_module 模 块 实现 ) 等 。 





如 此 一 来 ， 事 件 处 理 框架 需要 在 不 同 的 操作 系统 内 核 中 选择 一 种 事 
件 驱 动机 制 支持 网 络 事件 的 处 理 (Nginx 的 高 可 移植 性 亦 来 源 于 此 ) 。 
Nginx 是 如 何 做 到 这 一 点 的 呢 ? 


首先 ， 它 定义 了 一 个 核心 模块 ngx_events_module， 这 样 在 Nginx 启 
动 时 会 调用 ngx_init_cycle 方 法 解析 配置 项 ， 一 旦 在 nginx.conf 配 置 文件 
中 找到 ngx_events_module 感 兴趣 的 “events{}” 配 置 项 ， 
ngx_events_module 模 块 就 开始 工作 了 。 在 图 9-3 中 ，ngx_events_module 
模块 定义 了 事件 类 型 的 模块 ， 它 的 全 部 工作 就 是 为 所 有 的 事件 模块 解 
析 “events{}” 中 的 配置 项 ， 同 时 管理 这 些 事件 模块 存储 配置 项 的 结构 
体 。 





其 次 ，Nginx 定 义 了 一 个 非常 重要 的 事件 模块 
ngx_event_core_module， 这 个 模块 会 决定 使 用 哪 种 事件 驱动 机 制 ， 以 及 
如 何 管理 事件 。 在 9.5 节 中 ， 将 会 详细 讨论 ngx_event_core_module 模 块 在 
启动 过 程 中 的 工作 ， 而 在 9.8 节 中 ， 则 会 在 事件 框架 的 正常 运行 中 再 次 
看 到 ngx_event_core_module 模 块 的 “身影 ”。 





最 后 ，Nginx 定 义 了 一 系列 (目前 为 9 个 ) 运行 在 不 同 操作 系统 、 不 
同 内 核 版 本 上 的 事件 驱动 模块 ， 包 括 : ngx_epoll_module、 
ngx_kqueue module、 ngx_poll module、 ngx_select _ module、 
ngx_devpoll module、 ngx_eventport_module、ngx_aio_module、 


ngx_rtsig_module 和 基于 Windows 的 ngx_select_module 模 块 。 在 


ngx_event_core_module 模 块 的 初始 化 过 程 中 ， 将 会 从 以 上 9 个 模块 中 选 
取 1 个 作为 Nginx 进 程 的 事件 驱动 模块 。 





下 面 开始 介绍 事件 驱动 模块 接口 的 相关 知识 。 


事件 模块 是 一 种 新 的 模块 类 型 ，ngx_module t 表 示 Nginx 模 块 的 基 
本 接口 ， 而 针对 于 每 一 种 不 同类 型 的 模块 ， 都 有 一 个 结构 体 来 描述 这 一 
类 模块 的 通用 接口 ， 这 个 接口 保存 在 ngx_module_t 结 构 体 的 ctx 成 员 中 。 
例如 ， 核 心 模 块 的 通用 接口 是 ngx_core_module t 结 构 体 ， 而 事件 模块 的 
通用 接口 则 是 ngx_event_module_t 结 构 体 (参见 图 8-1) ， 具 体 如 下 所 


钞 。 





typedef struct { 
// 事件 模块 的 名 称 





ngx_str_t *name; 
// create_conf 和 


init_conf 方 法 的 调用 可 参见 图 


9-3 
// 在 解析 配置 项 前 ， 这 个 回调 方法 用 于 创建 存储 配置 项 参数 的 结构 体 


void *(*create_conf )(ngx_cycJle_t *cycle); 
/* 在 解析 配置 项 完成 后 ， 


init_conf 方 法 会 被 调用 ， 用 以 综合 处 理 当前 事件 模块 感 兴趣 的 全 部 配置 项 


*/ 
char *(*init_ conf)(ngx_cycle t *cycle, void *conf ) ， 
// 对 于 事件 驱动 机 制 ， 每 个 事件 模块 需要 实现 的 





10 个 抽象 方法 


ngx_event_actions_t actions ; 
} ngx_event module t; 








ngx_event_module_t 中 的 actions 成 员 是 定义 事件 驱动 模块 的 核心 方 
法 ， 下 面 重 点 看 一 下 actions 中 的 这 10 个 抽象 方法 ， 代 码 如 下 。 





typedef struct { 
/* 添 加 事件 方法 ， 它 将 负责 把 








1 个 感 兴趣 的 事件 添加 到 操作 系统 提供 的 事件 驱动 机 制 ( 如 


epoll.、 





kqueue 等 ) 中 ， 这 样 ， 在 事件 发 生 后 ， 将 可 以 在 调用 下 面 的 


process_events 时 获取 这 个 事件 


*/ 
ngx_int_t (*add)(ngx_event_t *ev, ngx_int_t event, ngx_uint_t flags); 
/* 删 除 事 件 方法 ， 它 将 把 





1 个 已 经 存在 于 事件 驱动 机 制 中 的 事件 移 除 ， 这 样 以 后 即使 这 个 事件 发 生 ， 调 用 


process_events 方 法 时 也 无 法 再 获取 这 个 事件 


4 
ngx_int_t (*del)(ngx_event_t *ev, ngx_int_t event, ngx_uint_t flags) 
/* 启 用 


1 个 事件 ， 目 前 事件 框架 不 会 调用 这 个 方法 ， 大 部 分 事件 驱动 模块 对 于 该 方法 的 实现 都 是 与 上 面 的 


add 方 法 完全 一 致 的 


*/ 
ngx_int_t (*enable)(ngx_event _t *ev, ngx_int_t event, ngx_uint_t flags); 
/禁用 





1 个 事件 ， 目 前 事件 框架 不 会 调用 这 个 方法 ， 大 部 分 事件 驱动 模块 对 于 该 方法 的 实现 都 是 与 上 面 的 





del 方 法 完全 一 致 的 


*/ 
ngx_int_t (*disable)(ngx_ event _t *ev, ngx_int_t event, ngx_uint_t flags); 
/* 向 事件 驱动 机 制 中 添加 一 个 新 的 连接 ， 这 意味 着 连接 上 的 读 写 事件 都 添加 到 事件 驱动 机 制 中 了 


*/ 
ngx_int_t (*add_ conn)(ngx_connection t *c); 
// 从 事件 驱动 机 制 中 移 除 一 个 连接 的 读 写 事件 


ngx_int_t (*del conn)(ngx_connection t *c, ngx_uint_t flags); 
/* 仅 在 多 线程 环境 下 会 被 调用 。 目 前 ， 


Nginx 在 产品 环境 下 还 不 会 以 多 线程 方式 运行 ， 因 此 这 里 不 做 讨论 


* 

/ 
ngx_int_t (*process changes) (ngx_cycle t *cycle, ngx_uint_t nowait); 
/* 在 正常 的 工作 循环 中 ， 将 通过 调用 





process_events 方 法 来 处 理事 件 。 这 个 方法 仅 在 第 


8 章 中 提 到 的 


ngx_process_events_and_timers 方 法 中 调用 ， 它 是 处 理 、 分 发 事件 的 核心 


wy4 
ngx_int t (*process events) (ngx_cycle t *cycle, ngx msec _t timer, ngx_ uint t 1 
// 初始 化 事件 驱动 模块 的 方法 


ngx_int_t (*init)(ngx_cycle_t *cycile, ngx_msec_t timer); 
// 退出 事件 驱动 模块 前 调用 的 方法 





void (*done)(ngx_cycle t *cycle); 
} ngx_event_actions _t; 


二 一 


9.2 Nginx 事 件 的 定义 


在 Nginx 中 ， 每 一 个 事件 都 由 ngx_event_t 结 构 体 来 表示 。 本 节 说 明 
ngx_event t 中 每 一 个 成 员 的 含义 ， 如 下 所 示 。 





typedef struct ngx_event_s ngx_event _t; 
struct ngx_event_s { 
/* 事 件 相关 的 对 象 。 通 常 








data 都 是 指向 


ngx_connection_t 连 接 对 象 。 开 启 文件 异步 


ngx_event_aio_t 结 构 体 


SS 
void *data; 
/* 标 志 位 ， 为 


1 时 表示 事件 是 可 写 的 。 通 常情 况 下 ， 它 表示 对 应 的 


TCP 连 接 目 前 状态 是 可 写 的 ， 也 就 是 连接 处 于 可 以 发 送 网 络 包 的 状态 


iA 
unsigned write:1; 
/* 标 志 位 ， 为 


1 时 表示 为 此 事件 可 以 建立 新 的 连接 。 通 常情 况 下 ,在 





ngx_cycle_t 中 的 


listening 动 态 数组 中 ， 每 一 个 监听 对 和 象 





ngx_listening_t 对 应 的 读 事件 中 的 


accept 标 志 位 才 会 是 


1*/ 
unsigned accept:1; 
/* 这 个 标志 位 用 于 区 分 当前 事件 是 否 是 过 期 的 ， 它 仅仅 是 给 事件 驱动 模块 使 用 的 ， 而 事件 消费 模块 可 不 用 关 ^ 


instance 标 志 位 来 避免 处 理 后 面 的 已 经 过 期 的 事件 。 在 


9.6 节 中 ， 将 详细 描述 


ngx_epoll_module 是 如 何 使 用 





instance 标 志 位 区 分 过 期 事件 的 ， 这 是 一 个 巧妙 的 设计 方法 


Wy4 
unsigned instance:1; 
/* 标 志 位 ， 为 





1 时 表示 当前 事件 是 活跃 的 ， 为 


日 时 表示 事件 是 不 活跃 的。 这 个 状态 对 应 着 事件 驱动 模块 处 理 方式 的 不 同 。 例如， 在 添加 事件 、 删 除 事 件 和 处 理事 人 





active 标 志 位 的 不 同 都 会 对 应 着 不 同 的 处 理 方式 。 在 使 用 事件 时 ， 一 般 不 会 直接 改变 


active 标 志 位 


SA 
unsigned active:1; 
/* 标 志 位 ， 为 


1 时 表示 禁用 事件 ， 仅 在 


kqueue 或 者 


rtsig 事 件 驱 动 模块 中 有 效 ， 而 对 于 


epo1ll 事 件 驱 动 模块 则 无 意义 ， 这 里 不 再 详 述 


*/ 
unsigned disabled:1; 
/* 标 志 位 ， 为 


1 时 表示 当前 事件 已 经 准备 就 绪 ， 也 就 是 说 ， 允 许 这 个 事件 的 消费 模块 处 理 这 个 事件 。 在 


HTTP 框 架 中 ， 经 常会 检查 事件 的 


ready 标 志 位 以 确定 是 否 可 以 接收 请 求 或 者 发 送 响应 


4 
unsigned ready:1; 
/* 该 标志 位 仅 对 
kqueue, 


eventport 等 模块 有 意义 ， 而 对 于 


Linux 上 的 


epo1ll 事 件 驱 动 模块 则 是 无 意义 的 ， 限 于 篇 幅 ， 不 再 详细 说 明 


4 
unsigned oneshot:1; 
// 该 标志 位 用 于 异步 


AIO 事 件 的 处 理 ， 在 


9.9 节 中 会 详细 描述 


unsigned complete:1; 
// 标志 位 ， 为 


1 时 表示 当前 处 理 的 字符 流 已 经 结束 


unsigned eof:1; 
// 标志 位 ， 为 


1 时 表示 事件 在 处 理 过 程 中 出 现 错误 


unsigned error:1; 
/* 标 志 位 ， 为 


1 时 表示 这 个 事件 已 经 超时 ， 用 以 提示 事件 的 消费 模块 做 超时 处 理 ， 它 与 


timer_set 都 用 于 


< 
unsigned timedout:1; 
// 标志 位 ， 为 


1 时 表示 这 个 事件 存在 于 定时 器 中 





unsigned timer_set:1; 
// 标志 位 ， 


delayed 为 


1 时 表示 需要 延迟 处 理 这 个 事件 ， 它 仅 用 于 限 速 功能 


unsigned delayed:1; 
// 该 标志 位 目前 没有 使 用 


unsigned read_discarded:1; 
// 标志 位 ， 目 前 这 个 标志 位 未 被 使 用 


unsigned unexpected eof:1; 
/* 标 志 位 ， 为 


1 时 表示 延迟 建立 


TCP 连 接 ， 也 就 是 说 ， 经 过 


TCP 三 次 握手 后 并 不 建立 连接 ， 而 是 要 等 到 真正 收 到 数据 包 后 才 会 建 


TCP 连 接 

< 
unsigned deferred accept:1; 
/* 标 志 位 ， 为 


aio 事 件 驱动 机 制 有 关 ， 不 再 详 述 


*/ 

unsigned pending_eof:1; 
#if !(NGX_THREADS) 

// 标志 位 ， 如 果 为 


1， 则 表示 在 处 理 





post 事 件 时 ， 当 前 事件 已 经 准备 就 绪 





unsigned posted_ready:1; 
#endif 
/* 标 志 位 ， 在 


epo11 事 件 驱 动机 制 下 表示 一 次 尽 可 能 多 地 建立 


TCP 连 接 ， 它 与 


multi_accept 配 置 项 对 应 ， 实 现 原理 参见 


9.8.1 节 


2 
unsigned available:1; 
// 这 个 事件 发 生 时 的 处 理 方法 ， 每 个 事件 消费 模块 都 会 重新 实现 它 








ngx_event_handler_pt handler; 
#if (NGX_HAVE_AIO) 
#if (NGX_HAVE_IOCP) 
// Windows 系 统 下 的 一 种 事件 驱动 模型 ， 这 里 不 再 详 述 





ngx_event_ovlp_t ovilp; 
#else 
// Linux aio 机 制 中 定义 的 结构 体 ， 在 


9.9 节 中 会 详细 说 明 它 


Struct aiocb aiocb ， 
#endif 
#endif 

// 由 于 


epol]1 事 件 驱 动 方式 不 使 用 


index， 所 以 这 里 不 再 说 明 


ngx_uint_t index; 
// 可 用 于 记录 


error_10g 日 志 的 


ngx_1og 七 对 象 


ngx_log_t *1og ; 


// 定时 器 节点 ， 用 于 定时 器 红 黑 树 中 ， 在 


ngx_rbtree_node_t timer; 
// 标志 位 ， 为 





1 时 表示 当前 事件 已 经 关闭 ， 


epoll1 模 块 没有 使 用 它 


unsigned closed:1; 
// 该 标志 位 目前 无 实际 意义 


unsigned channel:1; 
// 该 标志 位 目前 无 实际 意义 


unsigned resolver:1; 
/*post 事 件 将 会 构成 一 个 队列 再 统一 处 理 ， 这 个 队列 以 


next 和 


prev 作 为 链表 指针 ， 以 此 构成 一 个 简易 的 双向 链表 ， 其 中 


next 指 向 后 一 个 事件 的 地 址 ， 





prev 指 向 前 一 个 事件 的 地 址 


ngx_event_t *next; 
ngx_event_t **prev; 


}; 





每 一 个 事件 最 核心 的 部 分 是 handler 回 调 方法 ， 它 将 由 每 一 个 事件 消费 模块 实现 ， 以 此 决 











typedef void (*ngx_event_handler_pt)(ngx_event_t *ev); 





所 有 的 Nginx 模 块 只 要 处 理事 件 就 必然 要 设置 handler 回 调 方法 ， 后 续 章 市 会 有 许多 handle 





下 面 开 始 说 明 操作 事件 的 方法 。 





事件 是 不 需要 创建 的 ， 因 为 Nginx 在 启动 时 已 经 在 ngx_cycle_t 的 read_events 成 员 中 预 分 配 





先 看 一 下 ngx_handle_read_event 方 法 的 原型 : 








ngx_int_t ngx_handle_read event(ngx_event_t *rev, ngx_uint_t flags); 

















ngx_handle_read_event 方 法 会 将 读 事 件 添加 到 事件 驱动 模块 中 ， 这 样 该 事件 对 应 的 TCP 首 











下 面 看 一 下 ngx_handle_read_event 的 参数 和 返回 值 。 参 数 rev 是 要 操作 的 事件 ，flags 将 会 : 

















再 看 一 下 ngx_handle_write_event 方 法 的 原型 : 








ngx_int_t ngx_handle write event(ngx_event_t *wev, size _t lowat); 

















ngx_handle_write_event 方 法 会 将 写 事件 添加 到 事件 驱动 模块 中 。wev 是 要 操作 的 事件 ， 











一 般 在 向 epol 中 添加 可 读 或 者 可 写 事 件 时 ， 都 是 使 用 ngx_handle_read_event 或 者 ngx_han 








#define ngx_add_event ngx_event_actions.add 
#define ngx_del_event ngx_event_actions.del 
#define ngx_add_conn ngx_event_actions.add_conn 


#define ngx_del_conn ngx_event_actions.del conn 





9.3 ”Nginx 连 连接 的 定义 


作为 Web 服 务 嚣 ， 每 一 个 用 户 请 求 至 少 对 应 着 一 个 TCP 连 接 ， 为 了 
及 时 处 理 这 个 连接 ， 至 少 需要 一 个 读 事 件 和 一 个 写 事件 ， 使 得 epol 可 以 
有 效 地 根据 触发 的 事件 调度 相应 模块 读 取 请 求 或 者 发 送 啊 应 。 因 此 ， 
Nginx 中 定义 了 基本 的 数据 结构 ngx_connection t 来 表示 连接 ， 这 个 连接 
表示 是 客户 端 主动 发 起 的 、Nginx 服 务 器 被 动 接受 的 TCP 连 接 ， 我 们 可 
以 简单 称 其 为 被 动 连接 。 同 时 ， 在 有 些 请 求 的 处 理 过 程 中 ， ei 
图 主动 向 其 他 上 游 服务 器 建立 连接 ， 并 以 此 连接 与 上 游 服 务 器 通信， 
此 ， 这 样 的 连接 与 ngx_connection_t 又 是 不 同 的 ，Nginx 定 义 了 
ngx_peer_connection_t 结 构 体 来 表示 主动 连接 ， 当 然 ， 














ngx_peer_connection_t 主 动 连接 是 以 ngx_connection_t 结 构 体 为 基础 实现 
的 。 本 节 将 说 明 这 两 种 连接 中 各 字段 的 意义 ， 同 时 需要 注意 的 是 ， 这 两 
种 连接 都 不 可 以 随意 创建 ， 必 须 从 连接 池 中 获取 ， 在 9.3.3 节 中 会 说 明 连 
接 池 的 用 法 。 








9.3.1 被动 连接 





本 章 中 未 加 修饰 提 到 的 “连接 ”都 是 指 客户 端 发 起 的 、 服 务 器 被 动 接 
受 的 连接 ， 这 样 的 连接 都 是 使 用 ngx_connection_t 结 构 体 表示 的 ， 其 定义 
如 下 5 





typedef struct ngx_connection Ss ngx_connection t; 
struct ngx_connection s { 
/* 连 接 未 使 用 时 ， 


data 成 员 用 于 充当 连接 池 中 空闲 连接 链表 中 的 


next 指 针 。 当 连接 被 使 用 时 ， 


data 的 意义 由 使 用 它 的 


Nginx 模 块 而 定 ， 如 在 


HTTP 框 架 中 ， 


data 指 向 


ngx_http_request 七 请 求 


SA 
void *data; 
// 连接 对 应 的 读 事件 





ngx_event_t *read ; 
// 连接 对 应 的 写 事件 


ngx_event_t *write; 
// 套 接 字句 酉 


ngx_socket_t fd， 
// 直接 接收 网 络 字符 流 的 方法 


ngx_recv_pt recv 
// 直接 发 送 网 络 字符 流 的 方法 


ngx_send_pt send,; 
// 以 


ngx_chain_t 链 表 为 参数 来 接收 网 络 字 符 流 的 方法 


ngx_recv_chain pt recv_chain,; 
// 以 


ngx_chain_t 链 表 为 参数 来 发 送 网 络 字符 流 的 方法 


ngx_send_ chain pt send_chain,; 
/这 个 连接 对 应 的 


ngx_listening 七 监听 对 象 ， 此 连接 由 


listening 监 听 端 口 的 事件 建立 


*/ 
ngx_listening t *listening; 
// 这 个 连接 上 已 经 发 送出 去 的 字 节 数 


off_t sent,; 
// 可 以 记录 日 志 的 


ngx_1og 七 对 象 


ngx_log_t *1og ; 
/* 内 存 池 。 一 般 在 


aCccept 一 个 新 连接 时 ， 会 创建 一 个 内 存 池 ， 而 在 这 个 连接 结束 时 会 销毁 内 存 池 。 注 意 ， 这 里 所 说 的 连接 是 指 成 功 


TCP 连 接 ， 所 有 的 


ngx_connection _t 结 构 体 都 是 预 分 配 的 。 这 个 内 存 池 的 大 小 将 由 上 面 的 


Jistening 监 听 对 和 象 中 的 


pool_size 成 员 决 定 


*/ 
ngx_pool t *pool; 
// 连接 客户 端的 
sockaddr 结 构 体 


Struct sockaddr *sockaddr; 


// sockaddr 结 构 体 的 长 度 


socklen_t socklen; 
// 连接 客户 端 字 符 串 形式 的 


IP 地 址 


ngx_str_t addr_text,; 
/* 本 机 的 监听 端口 对 应 的 


Sockaddr 结 构 体 ， 也 就 是 


listening 监 听 对 象 中 的 


sockaddr 成 员 


*/ 
struct sockaddr *]local sockaddr; 
/* 用 于 接收 、 缓 存 客户 端 发 来 的 字符 流 ， 每 个 事件 消费 模块 可 自由 决定 从 连接 池 中 分 配 多 大 的 空间 给 


buffer 这 个 接收 缓存 字段 。 例 如 ， 在 


HTTP 模 块 中 ， 它 的 大 小 决定 于 


client_header_buffer_size 配 置 项 





*/ 
ngx_buf_t *buffer; 
/* 该 字段 用 来 将 当前 连接 以 双向 链表 元 素 的 形式 添加 到 


ngx_cycle_t 核 心 结构 体 的 





reusable_connections_queue 双 向 链表 中 ， 表 示 可 以 重用 的 连接 


*/ 
ngx_queue_t queue ， 
/* 连接 使 用 次 数 。 


ngx_connection_t 结 构 体 每 次 建立 一 条 来 自 客户 端的 连接 ， 或 者 用 于 主动 向 后 端 服务 器 发 起 连接 时 人 


ngx_peer_connection_t 也 使 用 它 ) ， 


number 都 会 加 


下 
ngx_atomic_uint t number,; 
// 处 理 的 请 求 次 数 


ngx_uint_t requests; 
/* 缓 存 中 的 业务 类 型 。 任 何事 件 消费 模块 都 可 以 自 定义 需要 的 标志 位 。 这 个 





buffered 字 段 有 


8 位 ， 最 多 可 以 同时 表示 


8 个 不 同 的 业务 。 第 三 方 模块 在 自 定 义 


buffered 标 志 位 时 注意 不 要 与 可 能 使 用 的 模块 定义 的 标志 位 冲突 。 目 前 


openssl 模 块 定义 了 一 个 标志 位 : 


#define NGX_SSL_BUFFERED OxO1 
HTTP 官 方 模块 定义 了 以 下 标志 位 : 


#define NGX_HTTP_LOWLEVEL _ BUFFERED Oxf0O 
#define NGX_HTTP_WRITE_BUFFERED Ox10 
#define NGX_HTTP_GZIP_BUFFERED Ox20 
#define NGX_HTTP_SSI_BUFFERED Ox0O1 
#define NGX_HTTP_SUB_BUFFERED Ox02 
#define NGX_HTTP_COPY_BUFFERED Ox04 
#define NGX_HTTP_IMAGE_ BUFFERED 0Xx08 同 时 ， 对 于 


HTTP 模 块 而 言 ， 


buffered 的 低 


4 位 要 慎 用 ， 在 实际 发 送 响应 的 


ngx_http_write_filter_module 过 滤 模 块 中 ， 低 





4 位 标志 位 为 


1 则 意味 着 


Nginx 会 一 直 认 为 有 


HTTP 模 块 还 需要 处 理 这 个 请 求 ， 必 须 等 待 


HTTP 模 块 将 低 


9 才 会 正常 结束 请 求 。 检 查 低 


4 位 的 宏 如 下 : 


#define NGX_ LOWLEVEL_ BUFFERED QOxOf 
2 

unsigned buffered:8; 
/* 本 连接 记录 日 志 时 的 级 别 ， 它 占用 了 


3 位 ， 取 值 范 围 是 


9~7; 但 实际 上 目前 及 定义 了 


5 个 值 ， 由 


ngx_connection_ 1og_error_e 枚 举 表 示 ， 如 下 : 


typedef enum { 
NGX_ERROR_ALERT = 0, 
NGX_ERROR_ERR, 
NGX_ERROR_INFO, 
NGX_ERROR_IGNORE_ECONNRESET, 
NGX_ERROR_IGNORE_EINVAL 

} ngx_connection_log_error_e; 

*/ 
unsigned lo0g_error:3; 
/* 标 志 位 ， 为 








1 时 表示 独立 的 连接 ， 如 从 客户 端 发 起 的 连接 ; 为 


9 时 表示 依靠 其 他 连接 的 行为 而 建立 起 来 的 非 独立 连接 ， 如 使 用 


Upstream 机 制 向 后 端 服务 器 建立 起 来 的 连接 


< 
unsigned single connection:1,; 


// 标志 位 ， 为 


1 时 表示 不 期 待 字 符 流 结束 ， 目 前 无 意义 


unsigned unexpected_ eof:1; 
// 标志 位 ， 为 


1 时 表示 连接 已 经 超时 


unsigned timedout:1; 
// 标志 位 ， 为 


1 时 表示 连接 处 理 过 程 中 出 现 错误 


unsigned error:1; 
/* 标 志 位 ， 为 


1 时 表示 连接 已 经 销毁 。 这 里 的 连接 指 是 的 


TCP 连 接 ， 而 不 是 


ngx_connection_t 结 构 体 。 当 


destroyed 为 


1 时 ， 


ngx_connection_t 结 构 体 仍然 存在 ， 但 其 对 应 的 套 接 字 、 内 存 池 等 已 经 不 可 用 


4 
unsigned destroyed:1; 
/* 标 志 位 ， 为 


1 时 表示 连接 处 于 空闲 状态 ， 如 


keepalive 请 求 中 两 次 请 求 之 间 的 状态 


*/ 
unsigned idle:1; 
// 标志 位 ， 为 


1 时 表示 连接 可 重用 ， 它 与 上 面 的 


queue 字 段 是 对 应 使 用 的 


unsigned reusable:1; 
// 标志 位 ， 为 


1 时 表示 连接 关闭 


unsigned close:1; 
// 标志 位 ， 为 


1 时 表示 正在 将 文件 中 的 数据 发 往 连 接 的 另 一 端 


unsigned sendfile:1; 
/* 标 志 位 ， 如 果 为 








1， 则 表示 只 有 在 连接 套 接 字 对 应 的 发 送 缓冲 区 必须 满足 最 低 设置 的 大 小 阅 值 时 ， 事 件 驱 动 模块 才 会 分 发 该 事件 。3 


ngx_handle_write_event 方 法 中 的 





]owat 参 数 是 对 应 的 


sp 
unsigned sndlowat:1; 
/* 标 志 位 ， 表 示 如 何 使 用 


TCP 的 


nodelay 特 性 。 它 的 取 值 范围 是 下 面 这 个 枚 举 类 型 


ngx_connection_tcp_nodelay_e: 


typedef enum { 
NGX_TCP_NODELAY_UNSET = 0， 
NGX_TCP_NODELAY_SET ， 
NGX_TCP_NODELAY_DISABLED 
} ngx_connection_tcp_nodelay_e; 
*/ 
unsigned tcp_nodelay:2; 
/* 标 志 位 ， 表 示 如 何 使 用 


TCP 的 


nopush 特 性 。 它 的 取 值 范围 是 下 面 这 个 枚 举 类 型 


ngx_connection_tcp_nopush_e: 


typedef enum { 
NGX_TCP_NOPUSH_UNSET = 0， 
NGX_TCP_NOPUSH_SET, 
NGX_TCP_NOPUSH_DISABLED 
} ngx_connection_tcp_nopush_e; 
*/ 
unsigned tcp_nopush:2; 
#if (NGX_HAVE_AIO_SENDFILE) 
// 标志 位 ， 为 


1 时 表示 使 用 异步 


I/0 的 方式 将 磁盘 上 文件 发 送 给 网 络 连 接 的 另 一 端 


unsigned aio_sendfile:1; 
// 使 用 异步 


I/0 方 式 发 送 的 文件 ， 


busy_sendfile 缓 冲 区 保存 待 发 送 文 件 的 信息 
ngx_buf_t *busy_sendfile; 


#endif 
}; 





和 


链表 中 的 recv、send、recv_chain、send_chain 这 4 个 关于 接收 、 发 送 网 络 字符 流 


的 方 








typedef ssize t (*ngx_recv_pt)(ngx_connection t *c, u_char *buf, size t size); 





typedef ssize t (*ngx_recv_chain_pt)(ngx_connection t *c, 








ngx_chain_t *in); 


typedef ssize t (*ngx_send pt)(ngx_connection t *c, u_char *buf, size t size); 
typedef ngx_chain t *(*ngx_send chain pt)(ngx_connection t *c, ngx_chain_t *in, off_t limit); 














这 4 个 成 员 以 方法 指针 的 形式 出 现 ， 说 明 每 个 连接 都 可 以 采用 不 同 的 接收 方法 ， 每 个 事 人 


9.3.2 ”主动 连接 


作为 Web 服 务 器 ，Nginx 也 需要 向 其 他 服务 器 主动 发 起 连接 ， 当 然 ， 这 样 的 连接 与 上 一 六 





typedef struct ngx_peer_connection s ngx_peer_connection t; 


// 当 使 用 长 连接 与 上 游 服务 器 通信 时 ， 可 通过 该 方法 由 连接 池 中 获取 一 个 新 连接 


typedef ngx_int_t (*ngx_event_get_peer_pt) (ngx_peer_connection t *pc,void *data); 


// 当 使 用 长 连接 与 上 游 服务 器 通信 时 ， 通 过 该 方法 将 使 用 完毕 的 连接 释放 给 连接 池 





typedef void (*ngx_event_free peer_pt) (ngx_peer_connection t *pc, void *data,ngx uint _t state); 
struct ngx_peer_connection s { 


/* 一 个 主动 连接 实际 上 也 需要 





ngx_connection_t 结 构 体 中 的 大 部 分 成 员 ， 并 且 出 于 重用 的 考虑 而 定义 了 
connection 成 员 


*/ 
ngx_connection _t *connection; 


// 远 端 服务 器 的 


socket 地 址 


Struct sockaddr *sockaddr; 


// sockaddr 地 址 的 长 度 


socklen_t socklen; 


// 远 端 服务 器 的 名 称 


ngx_str_t *name; 


/* 表 示 在 连接 一 个 远 端 服务 器 时 ， 当 前 连接 出 现 异 常 失败 后 可 以 重 试 的 次 数 ， 也 就 是 允许 的 最 多 失败 次 数 





EA 
ngx_uint_t tries; 


// 获取 连接 的 方法 ， 如 果 使 用 长 连接 构成 的 连接 池 ， 那 么 必须 要 实现 
get 方 法 


ngx_event_get_peer_pt get; 
po 


get 方 法 对 应 的 释放 连接 的 方法 


ngx_event_free peer_pt free; 
/* 这 个 


data 指 针 仅 用 于 和 上 面 的 

get、 

free 方 法 配合 传递 参数 ， 它 的 具体 含义 与 实现 
get 方 法 、 

free 方 法 的 模块 相关 ， 可 参照 
ngx_event_get_peer_pt 和 
ngx_event_free_peer_pt 方 法 原型 中 的 


data 参 数 


人 
void *data; 


// 本 机 地 址 信息 


ngx_addr_t *local; 


// 套 接 字 的 接收 缓冲 区 大 小 


int rcvbuf; 


// 记录 日 志 的 
ngx_log_t 对 象 


ngx_1og_t *log; 
// 标志 位 ， 为 


1 时 表示 上 面 的 


connection 连 接 已 经 缓存 


unsigned cached :1 


人 二 
9.3.1 节 中 
ngx_connection_t 里 的 
1og_error 意 义 是 相同 的 ， 区 别 在 于 这 里 的 
1og_error 只 有 两 位 ， 只 能 表达 
4 种 错误 ， 


NGX_ERROR_IGNORE_EINVAL 错 误 无 法 表达 


A 
unsigned log_error:2; 
}; 








ngx_peer_connection_t 也 有 一 个 ngx_connection_t 类 型 的 成 员 ， 怎 么 理解 这 两 个 结构 体 之 上 i 


9.3.3 ngx_connection_t 连 接 池 


Nginx 在 接受 客户 端的 连接 时 ， 所 使 用 的 ngx_connection_t 结 构 体 都 是 在 启动 阶段 就 预 分 E 











从 图 9-1 中 可 以 看 出 ， 在 ngx_cycle_t 中 的 connections 和 free_connections 这 两 个 成 员 构成 了 - 








图 9-1 中 还 显示 了 事件 池 ，Nginx 认 为 每 一 个 连接 一 定 至 少 需要 一 个 读 事件 和 一 个 写 事 件 ， 





在 使 用 连接 池 时 ，Nginx 也 封装 了 两 个 方法 ， 见 表 9-1。 














如 果 我 们 开发 的 模块 直接 使 用 了 连接 池 ， 那 么 就 可 以 用 这 两 个 方法 来 获取 、 释 放 ngx_co 





yet | 


= 
[TT 辣 | [|| 
I 


free_connections 

I +free_connection n 

| +reusable_connections queue :ngx queue s 
| : ngx array ft 
| 

| 


预 分 配 的 


connection _n 个 连接 


| +shared memory: ngx_list { 
| +connection n 

| 1 +files mn 
TTT 枚 TTTT] ey 
read events 


write_events 


1 1 +old_cycle 
预 分 配 的 | +conf file 
connection _n 个 读 事 件 | 
























| 
+ngx_master process cycle() 
国 国 国 国 I | | +ngx_single_process cycle() 
人 +ngx_start worker processes() 
+ngx_ start_cache manager processes() 
预 分 配 的 +ngx_pass open_ channel() 
connection n 个 写 事 件 +ngx_signal worker processes() 


+ngx_reap children() 

+ngx_master process exit() 

+ngx_ worker process_cycle() 
+ngx_ worker process init () 

+ngx_ worker process exit() 
+ngx_cache manager process cycle() 
+ngx_process events and timers() 


在 connections 指 和 癌 的 连接 池 
中 ， 每 个 连接 所 需要 的 读 / 写 
事件 都 以 相同 的 数组 序号 对 
应 着 read_events、write_events 
读 / 写 事件 数组 ， 相 同 序号 下 
这 3 个 数组 中 的 元 素 是 配合 使 
用 的 














图 9-1 ngx_connection_t 连 接 池 示意 图 


表 9-1 连接 池 的 使 用 方法 





连接 池 操 作 方 法 名 执行 意义 
ngx connection t *ngx get connection s 是 这 条 连接 的 套 接 字 句柄 ， 从 连接 池 中 获取 一 个 ngx_connection ft 
(ngx_socket ts, ngx _ log t *log) log 则 是 记录 日 志 的 对 象 结构 体 ， 同 时 获取 相应 的 读 / 写 事件 
void ngx_free_connection 2 二 A 
Se c 是 需要 回收 的 连接 将 这 个 连接 回收 到 连接 池 中 


(ngx_connection t *c) 





9.4 ngx_events_module 核 心 模块 


ngx_events_module 模 块 是 一 个 核心 模块 ， 它 定义 了 一 类 新 模块 ， 事 
件 模 块 。 它 的 功能 如 下 : 定义 新 的 事件 类 型 ， 并 定义 每 个 事件 模块 都 需 
要 实现 的 ngx_event_module _t 接 口 (参见 9.1.1 节 ) ， 还 需要 管理 这 些 事 
件 模块 生成 的 配置 项 结构 体 ， 并 解析 事件 类 配置 项 ， 当 然 ， 在 解析 配置 
项 时 会 人 command_t 数 组 中 定义 的 回调 方法 。 这 些 过 程 在 下 
文中 都 会 介绍 ， 不 过 ， 首 先 还 是 看 一 下 ngx_events_module 模 块 的 定义 。 





就 像 在 第 3 草 中 我 们 曾经 做 过 的 一 样 ， 定 义 一 个 Nginx 模 块 就 是 在 实 
现 ngx_modult_t 结 构 体 。 这 里 需要 先 定义 好 ngx_command_t〔 决 定 这 个 
模块 如 何 处 理 自己 感 兴趣 的 配置 项 ) 数组 ， 因 为 任何 模块 都 是 以 配置 项 
来 定制 功能 的 。ngx_events_commands 数 组 决定 了 ngx_events_module 模 
块 是 如 何 定制 其 功能 的 ， 代 码 如 下 。 





static ngx_command_t ngx events commands[] = { 

{ ngx_string("events"), 
NGX_MAIN_CONF|NGX_CONF_BLOCK|NGX_CONF_NOARGS, 
ngx_events_block, 

0, 

0, 
NULL }, 
ngx_null command 








可 以 看 到 ，ngx_events_module 模 块 只 对 一 个 块 配 置 项 感 兴 趣 ， 也 就 
是 nginx.conf 中 必须 有 的 events{...} 配 置 项 。 注 意 ， 这 里 暂时 先 不 要 关心 


ngx_events_block 方 法 是 如 何 处 理 这 个 配置 项 的 。 


作为 核心 模块 ，ngx_events_module 还 需要 实现 核心 模块 的 共同 接口 


ngx_core_module_t， 如 下 所 示 。 





static ngx_core module t ngx_events module ctx = { 
ngx_string("events"), 
NULL, 
NULL 

}; 








可 以 看 到 ，ngx_events_module_ctx 实 现 的 接口 只 是 定义 了 模块 名 字 
而 已 ，ngx_core_module_t 接 口中 定义 的 create_conf 方 法 和 init_conf 方 法 
都 没有 实现 NULL 空 指针 即 为 不 实现 ) ， 为 什么 呢 ? 这 是 因为 
ngx_events_module 模 块 并 不 会 解析 配置 项 的 参数 ， 只 是 在 出 现 events 配 
置 项 后 会 调用 各 事件 模块 去 解析 events{...} 块 内 的 配置 项 ， 自 然 就 不 需 
要 实现 create_conf 方 法 来 创建 存储 配置 项 参数 的 结构 体 ， 也 不 需要 实现 
init_conf 方 法 处 理解 析出 的 配置 项 。 





最 后 看 一 下 ngx_events_module 模 块 的 定义 代码 如 下 。 





ngx_module _t ngx_events module = { 
NGX_MODULE_V1, 








&ngx_events_module_ctx, /* module context */ 
ngx_events_commands, /* module directives */ 
NGX_CORE_MODULE, /* module type */ 

NULL, /* init master */ 

NULL, /* init module */ 

NULL， /* init process */ 
NULL, /* init thread */ 

NULL, /* exit thread */ 

NULL， /* exit process */ 
NULL, /* exit master */ 


NGX_MODULE_V1_PADDING 
}; 


可 见 ， 除 了 对 events 配 置 项 的 解析 外 ， 该 模块 没有 做 其 他 任何 事 
情 。 下 面 开 始 介绍 在 解析 events 配 置 块 时 ，ngx_events_block 方 法 做 了 些 
什么 。 


9.4.1 如 何 管理 所 有 事件 模块 的 配置 项 


上 文 说 过 ， 每 一 个 事件 模块 都 必须 实现 ngx_event_module_t 接 口 ， 
这 个 接口 中 允许 每 个 事件 模块 建立 自己 的 配置 项 结构 体 ， 用 于 存储 感 兴 
趣 的 配置 项 在 nginx.conf 中 对 应 的 参数 。ngx_event_module_t 中 的 
create_conf 方 法 就 是 用 于 创建 这 个 结构 体 的 方法 ， 事 件 模 块 只 需要 在 这 
个 方法 中 分 配 内 存 即 可 ， 但 这 个 内 存 指 针 是 如 何 由 ngx_events_module 模 
块 管理 的 呢 ? 下 面 来 看 一 下 这 些 事件 模块 的 配置 项 指针 是 如 何 被 存放 
的 ， 如 图 9-2 所 示 。 











每 一 个 事件 模块 产生 的 配置 结构 体 指 针 都 会 被 放 到 
ngx_events_module 模 块 创建 的 指针 数组 中 ， 可 这 个 指针 数组 又 存放 到 哪 
里 呢 ? 看 一 下 ngx_cycle _t 核 心 结构 体 中 的 conf_ctx 成 员 ， 它 指向 一 个 指 
针 数 组 ， 而 这 个 指针 数组 中 就 依次 存放 着 所 有 的 Nginx 模 块 关 于 配置 项 
方面 的 指针 。 在 默认 的 编译 顺序 下 ， 从 ngx_modules.c 文 件 中 可 以 看 到 
ngx_events_module 模 块 是 在 ngx_modules 数 组 中 的 第 4 个 位 置 ， 因 此 ， 所 
有 进程 的 conf_ctx 数 组 的 第 4 个 指针 就 保存 着 上 面 说 过 的 





ngx_events_module 模 块 创建 的 指针 数组 。 解 释 是 不 是 有 点 绕 ? 再 回顾 一 
下 ngx_cycle_t 结 构 体 中 的 conf_ctx 的 定义 : 





void ****conf_ctx; 





为 什么 上 面 代码 中 有 4 个 *? 因为 它 首 先 指 同 一 个 存放 指针 的 数组 ， 
这 个 数组 中 的 指针 成 员 同 时 又 指 回 了 男 外 一 个 存放 指针 的 数组 ， 所 以 是 
4 个 *。 看 到 conf_ctx 的 奥秘 了 吧 。 只 有 拥有 了 这 个 conf_ctx， 才 可 以 看 到 
任意 一 个 模块 在 create_conf 中 产生 的 结构 体 指针 。 同 理 ，HTTP 模 块 和 
mail 模 块 也 是 这 样 做 的 ， 这 些 模块 的 通用 接口 中 也 有 create_conf 方 法 ， 
其 产生 的 指针 会 以 相似 的 方式 存放 。 


每 一 个 事件 模块 如 何 获取 它 在 create_conf 中 分 配 的 结构 体 的 指针 
呢 ? ngx_events_module 定 义 了 一 个 简单 的 宏 来 完成 这 个 功能 代码 ， 如 
人 





#define ngx_event_get conf(conf_ctx,module) \ 
(*(ngx_get_ conf(conf_ctx, ngx_events module))) [module.ctx_index]; 








ngx_get_conf 也 是 一 个 宏 ， 它 用 来 获取 图 9-1 中 第 一 个 数组 中 的 指 
针 ， 如 下 所 示 。 





#define ngx_get_ conf(conf_ctx, module) conf_ctx[module.index] 





此 ， 调 用 ngx_event_get_conf 时 只 需要 在 第 1 个 参数 中 传 入 


ngx_cycle_t 中 的 conf_ctx 成 员 ， 在 第 2 个 参数 中 传 入 自己 的 模块 名 ， 束 可 
以 获取 配置 项 结构 体 的 指针 。 详 细 内 容 可 参见 9.6.3 节 中 使 用 
ngx_epoll_module 的 ngx_epoll_init 方 法 获取 配置 项 的 例子 。 


ngx cycle 1 


+ conf _ctx 


所 有 核心 模块 的 配置 结构 体 指针 


+ free _connections 
+ free _connection _D 
+ reusable connections _ queue :ngx queue S 


由 ngx_modules 数 


: ngx array t 
+ open files: ngx list _t 
+ shared memory: ngx list _t 
+connection_n 


第 4 个 模块 是 ngx_events_module 
模块 ， 因 此 ，conf_ctx 数 组 中 第 4 
位 存储 着 模块 的 配置 项 指针 ， 在 
这 里 这 个 指针 定义 为 指向 另 一 个 





+files _n 
数组 + connections 
所 有 事件 模块 的 配置 结构 体 指 针 + read events 


+ Write _events 
人 + old_cycle 
+ conf file 
conf _prefix 
+ prefix 
+lock file 
+ hostname 
+ngx master process _cycle () 
+ngx single_ process _cycle () 
+ngx start worker processes () 


事件 模块 1 中 create_conf 








方法 创建 的 结构 体 +ngx start _ cache manager processes() 
+ ngx_pass_open channel () 
+ngx signal worker processes () 
事件 模块 2 中 create_conf +ngx reap _children () 
方法 创建 的 结构 体 +ngx master process exit () 
+ ngx worker process_ cycle () 
+ ngx worker process_ init () 
事件 模块 3 中 create conf ngx_worker_process_ exit () 
方法 创建 的 结构 体 ngx_cache_ manager process_cycle () 





ngx process events and timers () 


事件 模块 4 中 create_conf 


方法 创建 的 结构 体 





图 9-2 ”所 有 事件 模块 配置 项 结构 体 的 指针 是 如 何 管 理 的 


9.4.2 ”管理 事件 模块 


上 文 说 到 ， 配 置 项 结构 体 指 针 的 保存 都 是 在 ngx_events_block 方 法 
中 进行 的 。 下 面 再 来 看 一 下 这 个 方法 执行 的 流程 图 ， 如 图 9-3 所 示 。 


1 ) 初始 化 所 有 事件 模块 的 ctx _index 序号 





2 ) 分 配 指针 数组 ,存储 所 有 事件 模块 生成 的 配置 项 结构 体 指针 


1 日 





吉 调用 所 有 事件 模块 的 create conf 方法 





4 ) 为 所 有 事件 模块 解析 nginx .conf 配置 文件 


5 调用 所 有 事 件 模 块 的 init _conf 方法 





重 


图 9-3 ”ngx_events_module 核 心 模 块 如 何 加 载 事件 模块 


1) 首先 初始 化 所 有 事件 模块 的 ctx_index 成 员 。 这 里 要 先 回顾 一 下 
ngx_module_t 横 块 接口 的 定义 ， 如 下 所 示 。 





struct ngx_module s { 
ngx_uint_t ctx_index; 
ngx_uint_t index; 








这 里 的 index 是 所 有 模块 在 ngx_modules.c 文 件 的 ngx_modules 数 组 中 
的 序号 ， 它 与 ngx_modules 数 组 中 所 有 模块 的 顺序 是 一 致 的 。 什 么 时 候 
初始 化 这 个 index 呢 ? 启动 Nginx 后 ， 在 调用 第 8 章 中 介绍 过 的 
ngx_init_cycle 方 法 前 就 会 进行 ， 代 人 码 如 下 。 





ngx_max_module = 0; 
for (i = 0; ngx_ modules[i]; i++) { 
ngx_modules[i]->index = ngx_max_module++; 


} 








其 中 ，ngx_max_module 是 Nginx 模 块 的 总 个 数 。 注 章 ， 本 书 前 文 曾 
多 次 提 到 过 ，Nginx 各 模块 在 ngx_modules 数 组 中 的 顺序 是 很 重要 的 ， 依 
徘 index 成 员 ， 每 一 个 模块 才 可 以 把 自己 的 位 置 与 其 他 模块 的 位 置 进行 
比较 ， 并 以 此 决定 行为 。 但 是 ，Nginx 同 时 又 允许 再 次 定义 子 类 型 ， 如 
事件 类 型 、HTTP 类 型 、mail 类 型 ， 那 同一 类 型 的 模块 间 叉 如 何 区 分 顺 
序 呢 《依靠 mdex 当 然 可 以 区 分 顺序 ， 但 index 是 针对 所 有 模块 的 ， 这 样 








效率 太 兰 ) ? 这 就 得 依靠 ctx_index 成 员 了 。ctx_index 表 明了 模块 在 相同 
类 型 模块 中 的 顺序 。 





此 ，ngx_events_block 方 法 的 第 一 步 就 是 初始 化 所 有 事件 模块 的 
ctx_index 成 员 ， 这 会 决定 以 后 加 载 各 事件 模块 的 顺序 。 其 代码 非常 简 
单 ;, 如 下 所 示 。 


ngx_event_max_module = 0; 
for (i = 0; ngx_ modules[i]; i++ 
if (ngx_modules[i]->type != NGX_EVENT MODULE) { 
continue 


ngx_modules[i]->ctx_index = ngx_event max_ module++; 


} 


其 中 ，ngx_event_max_module 是 编译 进 Nginx 的 所 有 事件 模块 的 总 
个 数 。 


2) 分 配 9.4.1 节 中 介绍 的 指针 数组 ， 不 再 详 述 。 


3) 依次 调用 所 有 事件 模块 通用 接口 ngx_event_module t 中 的 
create_conf 方 法 ， 当 然 ， 产 生 的 结构 体 的 指针 保存 在 上 面 的 指针 数组 
中 。 





4) 针对 所 有 事件 类 型 的 模块 解析 配置 项 。 这 时 ， 每 个 事件 模块 定 
义 的 ngx_command_t 决 定 了 配置 项 的 解析 方法 ， 如 果 在 nginx.conf 中 发 现 
相应 的 配置 项 ， 束 会 回调 各 事件 模块 定义 的 方法 。 


5) 解析 完 配 置 项 后 ， 依 次 调用 所 有 事件 模块 通用 接口 
ngx_event_module_t 中 的 init_conf 方 法 ， 实 现 了 这 个 方法 的 事件 模块 可 以 
在 此 做 一 些 配置 参数 的 整合 工作 。 





以 上 就 是 ngx_events_module 模 块 的 核心 工作 流程 。 对 于 事件 驱动 机 
制 ， 更 多 的 工作 是 在 ngx_event_core_module 模 块 中 进行 的 ， 下 面 继 续 看 
= 下 这 个 模块 检 了 此 什么; 





9.5 ngx_event_core_module 事 件 模 块 


ngx_event_core_module 模 块 是 一 个 事件 类 型 的 模块 ， 它 在 所 有 事件 
模块 中 的 顺序 是 第 一 位 (configure 执 行 时 必须 把 它 放 在 其 他 事件 模块 之 
前 )。 这 残 保 证 了 它 会 先 于 其 他 事件 模块 执行 ， 由 此 它 选择 事件 驱动 机 
制 的 任务 才 可 以 完成 。 








ngx_event_core_module 模 块 要 完成 哪些 任务 呢 ? 它 会 创建 9.3 市 中 介 
绍 的 连接 池 (包括 读 / 写 事件 ) ， 同 时 会 决定 究竟 使 用 哪些 事件 驱动 机 
制 ， 以 及 初始 化 将 要 使 用 的 事件 模块 。 


下 面 先 来 看 一 下 ngx_event_core_module 模 块 对 哪些 配置 项 感 兴趣 。 
该 模块 定义 了 ngx_event_core_commands 数 组 处 理 其 感 兴趣 的 7 个 配置 
项 ， 以 下 进行 简要 说 明 。 





static ngx_command t ngx_event core commands[] = { 
/* 连 接 池 的 大 小 ， 也 就 是 每 个 





worker 进 程 中 支持 的 


TCP 最 大 连接 数 ， 它 与 下 面 的 


connections 配 置 项 的 意义 是 重复 的 ， 可 参照 





9.3.3 节 理解 连接 池 的 概念 


7 
{ ngx_string("worker_connections"), 
NGX_EVENT_CONF |NGX_CONF_TAKE1., 


ngx_event_connections, 
9， 
90， 
NULL }, 
// 连接 池 的 大 小 ， 与 


worker_connections 配 置 项 意义 相同 


{ ngx_string("connections"), 
NGX_EVENT_CONF |NGX_CONF_TAKE1., 
ngx_event_connections, 

0, 
0, 
NULL }, 
// 确定 选择 哪 一 个 事件 模块 作为 事件 驱动 机 制 


{ ngx_string("use"), 
NGX_EVENT_CONF |NGX_CONF_TAKE1., 
ngx_event_use, 

0, 
0, 

NULL }, 

/对 应 于 


9.2 节 中 提 到 的 事件 定义 的 





available 字 段 。 对 于 
epoll 事 件 驱动 模式 来 说 ， 意 味 着 在 接收 到 一 个 新 连接 事件 时 ， 调 用 
accept 以 尽 可 能 多 地 接收 连接 


*/ 

{ ngx_string("multi accept"), 
NGX_EVENT_CONF |NGX_CONF_FLAG, 
ngx_conf_set_flag_slot, 

0, 
offsetof(ngx_event_conf_t, multi accept), 
NULL }, 
// 确定 是 否 使 用 





accept_mutex 负 载 均衡 锁 ， 默 认为 开启 


{ ngx_string("accept_mutex"), 
NGX_EVENT_CONF |NGX_CONF_FLAG, 
ngx_conf_set_flag_slot, 

0, 
offsetof(ngx_event_conf_t, accept_mutex), 





NULL }, 
/* 启 用 


accept_mutex 负 载 均 衡 锁 后 ， 延 迟 


accept_mutex_delay 毫 秒 后 再 试图 处 理 新 连接 事件 


4 
{ ngx_string("accept_ mutex_delay"), 
NGX_EVENT_CONF |NGX_CONF_TAKE1., 
ngx_conf_set_msec_slot, 





了 
offsetof(ngx_event_ conf_t, accept_ mutex_delay), 
NULL }, 

XZ/ 需要 对 来 育 指 定 


IP 的 
TCP 连 接 打 印 


debug 级 别 的 调试 日 志 


{ ngx_string("debug_connection"), 
NGX_EVENT_CONF |NGX_CONF_TAKE1., 
ngx_event_debug_connection, 

9, 
9, 

NULL }, 

ngx_null command 


}; 








值得 注意 的 是 ， 上 面 对 于 配置 项 参数 的 解析 使 用 了 在 第 4 章 中 介绍 
过 的 Nginx 预 设 的 配置 项 解析 方法 ， 如 ngx_conf _set_flag_slot 和 
ngx_conf_set_msec_slot。 这 种 自动 解析 配置 项 的 方式 是 根据 指定 结构 体 
中 的 位 置 决定 的 。 下 面 看 一 下 该 模块 定义 的 用 于 存储 配置 项 参数 的 结构 


体 ngx_event_conf t。 











pedef struct { 
// 连接 池 的 大 小 


ngx_uint_t connections ; 
/* 选 用 的 事件 模块 在 所 有 事件 模块 中 的 序号 ， 也 就 是 


9.4.2 节 中 介绍 过 的 


Ctx_index 成 员 


4 
ngx_uint_t use; 
// 标志 位 ， 如 果 为 


1， 则 表示 在 接收 到 一 个 新 连接 事件 时 ， 一 次 性 建立 尽 可 能 多 的 连接 





ngx_flag _t multi accept; 
// 标志 位 ， 为 


1 时 表示 启用 负载 均衡 锁 


ngx_flag _t accept_ mutex; 
/* 负载 均 衡 锁 会 使 有 些 


Worker 进 程 在 拿 不 到 锁 时 延迟 建立 新 连接 ， 


accept_mutex_delay 就 是 这 段 延迟 时 间 的 长 度 。 关 于 它 如 何 影 响 负 载 均衡 的 内 容 ， 可 参见 


9.8.5 节 


*/ 
ngx_msec_t accept_mutex_delay; 
// 所 选用 事件 模块 的 名 字 ， 它 与 


USe 成 员 是 匹配 的 


U_char *name 
#if (NGX_DEBUG ) 
1 全 


with-debug 编 译 模 式 下 ， 可 以 仅 针对 某 些 客户 端 建立 的 连接 输出 调试 级 别 的 上 日志， 而 


debug_connection 数 组 用 于 保存 这 些 客户 端的 地 址 信息 


*/ 

ngx_array_t debug_connection,; 
#endif 
} ngx_event_conf_t; 





ngx_event_conf_t 结 构 体 中 有 两 个 成 员 与 负载 均衡 锁 相 关 ， 读 者 可 
以 在 9.8 节 中 了 解 负载 均衡 锁 的 原理 。 


对 于 每 个 事件 模块 都 需要 实现 的 ngx_event_module_t 接 口 ， 
ngX_event_core_module 模 块 则 仅 实 现 了 create_conf 方 法 和 init_conf 方 法 ， 
这 是 因为 它 并 不 真正 负责 TCP 网 络 事件 的 驱动 ， 所 以 不 会 实现 
ngx_event_actions_t 中 的 方法 ， 如 下 所 示 。 





static ngx_Sstr t event_core_name = ngx_string("event_core"); 
ngx_event_ module t ngx_event core module ctx = { 
&event_core_name, 
ngx_event_create_conf, /* create configuration */ 
ngx_event_init_conf, /* init configuration */ 
{ NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL } 








}; 





最 后 看 一 下 ngx_event_core_module 模 块 的 定义 。 





ngx_module t ngx_ event core module = { 
NGX_MODULE_V1, 











&ngx_event_core_module_ctx, /* module context */ 
ngx_event_core_commands, /* module directives */ 
NGX_EVENT_MODULE, /* module type */ 

NULL, /* init master */ 
ngx_event_module_init, /* init module */ 
ngx_event_process_init, /* init process */ 
NULL, /* init thread */ 

NULL, /* exit thread */ 

NULL， /* exit process */ 
NULL, /* exit master */ 


NGX_MODULE_V1_PADDING 
}; 


它 实 现 了 ngx_event_module_init 方 法 和 ngx_event_process_init 方 法 。 
在 Nginx 启 动 过 程 中 还 没有 fork 出 worker 子 进程 时 ， 会 首先 调用 
ngx_event_core_module 模 块 的 ngx_event_module init 方 法 (参见 图 8- 
6) ， 而 在 fork 出 worker 子 进程 后 ， 每 一 个 worker 进 程 会 在 调用 
ngx_event_core_module 模 块 的 ngx_event_process_init 方 法 后 才 会 进入 正 
式 的 工作 循环 。 弄 清楚 这 两 个 方法 何 时 调用 后 ， 下 面 来 看 一 下 它们 究 况 
(A 








ngx_event_module_init 方 法 其 实 很 简单 ， 它 主要 初始 化 了 一 些 变 
量 ， 尤 其 是 ngx_http_stub_status_module 统 计 模 块 使 用 的 一 些 原子 性 的 统 
计 变 量 ， 这 里 不 再 详 述 。 

而 ngx_event_process_init 方 法 就 做 了 许多 事情 ， 下 面 开始 详细 介绍 
它 的 流程 。 

ngx_event_core_module 模 块 在 启动 过 程 中 的 主要 工作 都 是 在 
ngx_event_process_init 方 法 中 进行 的 ， 如 图 9-4 所 示 。 

下 面 对 以 上 13 个 步骤 进行 简要 说 明 。 


1) 当 打 开 accept_mutex 负 载 均衡 锁 ， 同 时 使 用 了 master 模 式 并 且 
worker 进 程 数 量 大 于 1 时 ， 才 正式 确定 了 进程 将 使 用 accept_mutex 负 和 载 均 
衡 锁 。 因 此 ， 即 使 我 们 在 配置 文件 中 指定 打开 accept_mutex 锁 ， 如 果 没 
有 使 用 master 模 式 或 者 worker 进 程 数 量 等 于 1， 进 程 在 运行 时 还 是 不 会 使 














用 负载 均衡 锁 (既然 不 存在 多 个 进程 去 抢 一 个 监 昕 端口 上 的 连接 的 情 
况 ， 那 么 自然 不 需要 均衡 多 个 worker 进 程 的 负载 〉。 


这 时 会 将 ngx_use_accept_mutex 全 局 变量 置 为 1， 
ngx_accept_mutex_held 标 志 设 为 0，ngx_accept_mutex_delay 则 设 为 在 配 
置 文件 中 指定 的 最 大 延迟 时 间 。 这 3 个 变量 的 意义 可 参见 9.8 节 中 关于 负 
载 均衡 锁 的 说 明 。 





2) 如 果 没 有 满足 第 1 步 中 的 3 个 条 件 ， 那 么 会 把 
ngx_use_accept_mnutex 置 为 0， 也 就 是 关闭 负载 均衡 锁 。 





3) 初始 化 红 黑 树 实现 的 定时 器 。 关 于 定时 器 的 实现 细节 可 参见 9.6 
i 
4) 在 调用 use 配 置 项 指定 的 事件 模块 中 ， 在 ngx_event_module_t 接 


口 下 ，ngx_event_actions_t 中 的 init 方 法 进行 这 个 事件 模块 的 初始 化 工 
Es 


打开 accept_mutex 配置 ，master 模 式 下 worker 进程 数量 大 于 ! ] 


2) 关闭 ngx_use_accept_mutex 锁 1) 打 开 ngx_use accept_mutex 锁 








3) 初始 化 红 黑 树 实现 的 
ngx_event_timer_rbtree 定 时 器 


4) 调用 use 配 秆 项 指定 的 事件 驱动 模块 的 





init 方法 


[使 用 timer _resolution 设 置 了 时 间 精 度 ] 











5) 指 定 timer_resolution 齐 秒 后 调用 
ngx_timer_signal_handler 方 法 


[使 用 POLL 事 件 驱 动 ] 


<》 


6) 问 cycle 人 files 数 组 预 分 配 运行 时 
使 用 的 连接 句柄 





7) 预 分 配 cycle 之 connections 





数组 充当 连接 池 


8 ) 预 分 配 所 有 读 事件 到 


cycle 一 read_events 














9) 预 分 配 所 有 写 事件 到 


cycle 之 write_events 数组 


10) 将 上 述 所 于 事件 放置 到 


connections 连 











11) 将 connetions pe 由 


cycle >free_connections 









12) 设置 监听 端口 上 读 事 件 的 处 理 方法 为 


ngx_event_accept 





13) 将 监听 连接 的 读 事件 添加 





到 事件 驱动 模块 


图 9-4 ngx_event_core_module 事 件 模块 启动 时 的 工作 流程 





5) 如 果 nginx.conf 配 置 文件 中 设置 了 timer_resolution 配 置 项 ， 即 表 
明 需 要 控制 时 间 精 上 度 ， 这 时 会 调用 setitimer 方 法 ， 设 置 时间 间 隔 为 
timer_resolution 毫 秒 来 回调 ngx_timer_signal_handler 方 法 。 下 面 简单 地 介 
绍 一 下 Nginx 是 如 何 控制 时 间 精 度 的 。 


ngx_timer_signal_handler 方 法 又 做 了 些 什么 呢 ? 其 实 非 篆 简 单 ， 如 
下 所 示 。 





void ngx_timer_signal handler(int signo) 





ngx_event_timer_alarm = 1; 


} 





ngx_event_timer_alarm 只 是 个 全 局 变量 ， 当 它 设 为 1 时 ， 表 示 需 要 更 


新 时 间 。 


在 ngx_event_actions_t 的 process_events 方 法 中 ， 每 一 个 事件 驱动 模 
块 都 需要 在 ngx_event_timer_alarm 为 1 时 调用 ngx_time_update 方 法 (参见 
9.7.1 节 ) 更 新 系统 时 间 ， 在 更 新 系统 结束 后 需要 将 


ngx_event_timer_alarm 设 为 0。 





6) 如 果 使 用 了 epoll 事 件 驱 动 模式 ， 那 么 会 为 ngx_cycle_t 结 构 体 中 
的 files 成 员 预 分 配 句柄 。 本 章 仅 针对 epol 事 件 驱 动 模式 ， 有 具体 内 容 不 再 


7) 预 分 配 ngx_connection_t 数 组 作为 连接 池 ， 同 时 将 ngx_cydle_t 结 


构 体 中 的 connections 成 员 指 问 该 数组 。 数 组 的 个 数 为 nginx.conf 配 置 文件 
中 connections 或 worker_connections 中 配置 的 连接 数 。 


8) 预 分 配 ngx_event_t 事 件数 组 作为 读 事 件 池 ， 同 时 将 ngx_cycle_t 
结构 体 中 的 read_events 成 员 指 同 该 数组 。 数 组 的 个 数 为 nginx.conf 配 置 文 
件 中 connections 或 worker_connections 里 配置 的 连接 数 。 


9) 预 分 配 ngx_event_t 事 件数 组 作为 写 事 件 闻 ， 同 时 将 ngx_cycle 
结构 体 中 的 write_events 成 员 指 同 该 数组。 数组 的 个 数 为 nginx.conf 配 置 
文件 中 connections 或 worker_connections 里 配置 的 连接 数 。 





10) 按照 序号 ， 将 上 述 3 个 数组 相应 的 读 / 写 事件 设置 到 每 一 个 
ngx_connection_t 连 接 对 象 中 ， 同 时 把 这 些 连接 以 ngx_connection_t 中 的 
data 成 员 作 为 next 指 针 串 联 成 链表 ， 为 下 一 步 设置 空闲 连接 链表 做 好 准 
备 ， 参 见 图 9-1。 





11) 将 ngx_cycle_t 结 构 体 中 的 空间 连接 链表 free_connections 指 问 
connections 数 组 的 最 后 1 个 元 素 ， 也 就 是 第 10 步 所 有 ngx_connection_t 连 
接 通过 data 成 员 组 成 的 单 链表 的 首部 。 














12) 在 刚刚 建立 好 的 连接 池 中 ， 为 所 有 ngx_listening_t 监 听 对 象 中 
的 connection 成 员 分 配 连接 ， 同 时 对 监听 端口 的 读 事 件 设 置 处 理 方 法 为 
ngx_event_accept， 也 就 是 说 ， 有 新 连接 事件 时 将 调用 ngx_event_accept 
方法 建立 新 连接 〈 详 见 9.8 市 中 关于 如 何 建立 新 连接 的 内 容 〉。 





13) 将 监听 对 象 连接 的 读 事 件 汶 加 到 事件 驱动 模块 中 ， 这 样 ，epoll 
等 事件 模块 束 开 始 检 测 监 昕 服务 ， 并 开始 向 用 户 提 供 服务 了。 注意 ， 打 


开 accept_mutex 锁 后 则 不 执行 这 一 步 。 





至 此 ，ngx_event_core_module 模 块 的 启动 工作 就 全 部 结束 了 。 下 面 
将 以 epoll 事 件 方式 为 例 来 介绍 实际 的 事件 驱动 模块 是 如 何 处 理事 件 的 。 





9.6 ”epoll 事 件 驱 动 模块 





本 章 9.1 节 ~9.5 节 都 在 探讨 Nginx 是 如 何 设 计 事件 驱动 框架 、 如 何 管 
理 不 同 的 事件 驱动 模块 的 ， 但 本 节 中 将 以 epoll 为 例 ， 讨 论 Linux 操 作 系 
统 内 核 是 如 何 实现 epoll 事 件 驱 动机 制 的 ， 在 简单 了 解 它 的 用 法 后 ， 会 进 
一 步 说 明 ngx_epoll_module 模 块 是 如 何 基于 epoll 实 现 Nginx 的 事件 驱动 
的 。 这 样 读者 就 会 对 Nginx 完 整 的 事件 驱动 设计 方法 有 全 面 的 了 解 ， 同 
时 可 以 弄 清楚 Nginx 在 几 十 万 并 发 连接 下 是 如 何 做 到 高 效 利用 服务 器 资 
源 的 。 





9.6.1 ”epoll 的 原理 和 用 法 








设想 一 个 场景 ， 有 100 万 用 户 同时 与 一 个 进程 保持 着 TCP 连 接 ， 而 
每 一 时 刻 只 有 几 十 个 或 几 百 个 TCP 连 接 是 活跃 的 (接收 到 TCP 包 ) ， 也 
就 是 说 ， 在 每 一 时 刻 ， 进 程 只 需要 处 理 这 100 万 连接 中 的 一 小 部 分 连 
接 。 那 么 ， 如 何 才 能 高 效 地 处 理 这 种 场景 呢 ? 进程 是 否 在 每 次 询问 操作 
系统 收集 有 事件 发 生 的 TCP 连 接 时 ， 把 这 100 万 个 连接 告诉 操作 系统 ， 
然后 由 操作 系统 找 出 其 中 有 事件 发 生 的 几 百 个 连接 呢 ? 实际 上 ， 在 
Linux 内 核 2.4 版 本 以 前 ， 那 时 的 select 或 者 poll 事 件 驱动 方式 就 是 这 样 做 
Ns 








这 里 有 个 非常 明显 的 问题 ， 即 在 某 一 时 刻 ， 进 程 收集 有 事件 的 连接 
时 ， 其 实 这 100 万 连接 中 的 大 部 分 都 是 没有 事件 发 生 的 。 因 此 ， 如 果 每 
次 收集 事件 时 ， 都 把 这 100 万 连接 的 套 接 字 传 给 操作 系统 〈 这 首先 就 是 
用 户 态 内 存 到 内 核 态 内 存 的 大 量 复制 ) ， 而 由 操作 系统 内 核 寻 找 这 些 连 
接 上 有 没有 未 处 理 的 事件 ， 将 会 是 巨大 的 资源 浪费 ， 然 而 select 和 poll 就 
是 这 样 做 的 ， 因 此 它们 最 多 只 能 处 理 几 千 个 并 发 连接 。 而 epoll 不 这 样 
做 ， 它 在 Linux 内 核 中 申请 了 一 个 简易 的 文件 系统 ， 把 原先 的 一 个 select 
或 者 poll 调 用 分 成 了 3 个 部 分 : 调用 epoll_create 建 并 1 个 epoll 对 象 ( 在 
epoll 文 件 系统 中 给 这 个 句柄 分 配 资源 ) 、 调 用 epollL_ctl 回 epol 对 象 中 添 
加 这 100 万 个 连接 的 套 接 字 、 调 用 epoll_wait 收 集 发 生 事件 的 连接 。 这 
样 ， 只 需要 在 进程 启动 时 建立 1 个 epoll 对 象 ， 并 在 需要 的 时 候 向 它 添加 
或 删除 连接 就 可 以 了 ， 因 此 ， 在 实际 收集 事件 时 ，epoll_wait 的 效率 就 
会 非常 高 ， 因 为 调用 epoll_wait 时 并 没有 向 它 传递 这 100 万 个 连接 ， 内 核 
也 不 需要 去 遍历 全 部 的 连接 。 











那么 ，Linux 内 核 将 如 何 实 现 以 上 的 想法 呢 ? 下面 以 Linux 内 核 
2.6.35 版 本 为 例 ， 简 单 说 明 一 下 epoll 是 如 何 高 效 处 理事 件 的 。 图 9-5 展 示 
了 epol 的 内 部 主要 数据 结构 是 如 何 安排 的 。 





当 某 一 个 进程 调用 epoll_create 方 法 时 ，Linux 内 核 会 创建 一 个 
eventpoll 结 构 体 ， 这 个 结构 体 中 有 两 个 成 员 与 epoll 的 使 用 方式 密切 相 
关 ， 如 下 所 示 。 


Struct eventpoll { 


/* 红 黑 树 的 根 节 点 ， 这 棵 树 中 存储 着 所 有 添加 到 


epoll 中 的 事件 ， 也 就 是 这 个 





ep0o1ll1 监 控 的 事件 


*7/ 
struct rb_root rbr; 
// 双向 链表 
rd11ist 保 存 着 将 要 通过 


epol1_wait 返 回 给 用 户 的 、 满 足 条 件 的 事件 


Struct list_head rdllist,; 


上 






eventpoll 
+ lock 


+ Ntx 
















红 黑 树 ! A 站 点 都 
是 基于 epitem 结 构 中 


的 rdllink 成 员 


+ rdllink 


ST Ba 
红 黑 树 中 + next 


全 一 » a es 
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图 9-5 ”epoll 原 理 示意 图 


每 一 个 epoll 对 象 都 有 一 个 独立 的 eventpoll 结 构 体 ， 这 个 结构 体会 在 
内 核 空间 中 创造 独立 的 内 存 ， 用 于 存储 使 用 epoll_ctl 方 法 向 epoll 对 象 中 
添加 进来 的 事件 。 这 些 事件 都 会 挂 到 rbr 红 黑 树 中 ， 这 样 ， 重 复 添 加 的 事 
件 就 可 以 通过 红 黑 树 而 高 效 地 识别 出 来 (epoll_ctl 方 法 会 很 快 ) 。Linux 
内 核 中 的 这 棵 红 黑 树 与 第 7 章 中 介绍 的 Nginx 红 黑 树 是 非常 相似 的 ， 可 以 


参照 ngx_rbtree_t 容 器 进行 理解 。 





所 有 添加 到 epoll 中 的 事件 都 会 与 设备 〈 如 网 卡 ) 驱动 程序 建立 回调 
关系 ， 也 就 是 说 ， 相 应 的 事件 发 生 时 会 调用 这 里 的 回调 方法 。 这 个 回调 
方法 在 内 核 中 叫做 ep_poll_callback， 它 会 把 这 样 的 事件 放 到 上 面 的 rdllist 
双 问 链表 中 。 这 个 内 核 中 的 双向 链表 与 ngx_queue_t 容 器 几乎 是 完全 相同 
的 《Nginx 代 码 与 Linux 内 核 代码 很 相似 )， 我 们 可 以 参照 着 理解 。 在 
epoll 中 ， 对 于 每 一 个 事件 都 会 建立 一 个 epitem 结 构 体 ， 如 下 所 示 。 





struct epitem { 


// 红 黑 树 节点 ， 与 第 
7 章 中 的 


ngx_rbtree_node t 红 黑 树 节点 相似 


struct rb_node rbn,; 
// 双向 链表 节点 ， 与 第 


7 章 中 的 


ngx_queue _t 双 向 链表 节点 相似 


struct list_head rdllink; 
// 事件 句柄 等 信息 


struct epoll filefd ffd， 
// 指向 其 所 属 的 


eventpol11 对 象 


struct eventpoll *ep; 
// 期 待 的 事件 类 型 





struct epoll event event 





这 里 包含 每 一 个 事件 对 应 着 的 信息 。 


当 调 用 epoll_wait 检 查 是 否 有 发 生 事 件 的 连接 时 ， 只 是 检查 eventpoll 
对 象 中 的 rdllist 双 向 链表 是 否 有 epitem 元 素 而 已 ， 如 果 rdllist 链 表 不 为 
空 ， 则 把 这 里 的 事件 复制 到 用 户 态 内 存 中 ， 同 时 将 事件 数量 返回 给 用 
户 。 因 此 ，epoll_wait 的 效率 非常 高 。epoll_ctl 在 癌 epoll 对 象 中 添加 、 修 
改 、 删 除 事 件 时 ， 从 rbr 红 黑 树 中 查找 事件 也 非常 快 ， 也 就 是 说 ，epoll 是 
非常 高 效 的 ， 它 可 以 轻易 地 处 理 百 万 级 别 的 并 发 连接 。 





9.6.2 ”如 何 使 用 epoll 
epoll 通 过 下 面 3 个 epoll 系 统 调 用 为 用 户 提供 服务 。 
(1) epoll_create 系 统 调用 
epoll_create 在 C 库 中 的 原型 如 下 。 


int epoll create(int size); 


epoll_create 返 回 一 个 句柄 ， 之 后 epol 的 使 用 都 将 依靠 这 个 句柄 来 标 


识 。 参 数 size 是 告诉 epoll 所 要 处 理 的 大 致 事件 数目 。 不 再 使 用 epoll 时 ， 
必须 调用 close 关 闭 这 个 句柄 。 


@ 注意 size 参数 只 是 告诉 内 核 这 个 epoll 对 象 会 处 理 的 事件 大 致 数 
目 ， 而 不 是 能 够 处 理 的 事件 的 最 大 个 数 。 在 Linux 最 新 的 一 些 内 核 版 本 
的 实现 中 ， 这 个 size 参 数 没有 任何 意义 。 


(2) epoll_ctl 系 统 调用 


epoll_ctl 在 C 库 中 的 原型 如 下 。 





int epoll ctl(int epfd,int op,int fd,struct epoll event* event); 





epoll_ctl 同 epoll 对 象 中 添加 、 修 改 或 者 删除 感 兴趣 的 事件 ， 返 回 0 表 
示 成 功 ， 否 则 返回 -1， 此 时 需要 根据 errno 错 误 但 判断 错误 类 型 。 
epoll_wait 方 法 返回 的 事件 必然 是 通过 epoll_ctl 添 加 到 epoll 中 的 。 参 数 
epfd 是 epoll_create 返 回 的 句柄 ， 而 op 参数 的 意义 见 表 9-2。 


表 9-2 epoll_ctl 系 统 调用 中 第 2 个 参数 的 取 值 意义 


op 的 取 值 意 义 
EPOLL CTL ADD 添加 新 的 事件 到 epoll 中 
EPOLL CTL MOD 修改 epoll 中 的 事件 
EPOLL CTL DEL 删除 epoll 中 的 事件 


第 3 个 参数 fq 是 待 监测 的 连接 套 接 字 ， 第 4 个 参数 是 在 告 0 
么 样 的 事件 感 兴趣 ， 它 使 用 了 epoll_event 结 构 体 ， 在 上 文 介绍 过 的 epoll 








实现 机 制 中 会 为 每 一 个 事件 创建 epitem 结 构 体 ， 而 在 epitem 中 有 一 个 
epoll_event 类 型 的 event 成 员 。 下 面 看 一 下 epoll_event 的 定义 。 





struct epoll event{ 
__Uint32_t events; 
epoll data t data; 


}; 





events 的 取 值 见 表 9-3。 


表 9-3 epoll_event 中 events 的 取 值 意义 


events 取 值 意 义 

示 对 应 的 连接 上 有 数据 可 以 读 出 连接 的 远 端 主动 关闭 连接 ， 也 相当 于 可 读 事 件 ， 

EPOLLIN 区 0 ts 0 H (TCP 连接 的 远 端 主动 关闭 连接 ， 也 相当 于 可 读 事件 
示 对 应 的 连接 上 可 以 写 入 数据 发 送 (主动 向 上 游 服务 器 发 起 非 阻 塞 的 TCP 连接 ， 连 接 

EPOLLOUT 人 | 向 上 游 服务 器 发 起 非 阻塞 的 TCP 连接 ， 连 接 

EPOLLRDHUP 表示 TCP 连接 的 远 端 关闭 或 半 关 闭 连接 

EPOLLPRI 表示 对 应 的 连接 上 有 紧急 数据 需要 读 

EPOLLERR 表示 对 应 的 连接 发 生 错误 

EPOLLHUP 表示 对 应 的 连接 被 挂 起 

EPOLLET 表示 将 触发 方式 设置 为 边缘 触发 (ET)， 系 统 默 认为 水 平 触 发 (LT) 

EPOLLONESHOT 表示 对 这 个 事件 只 处 理 一 次 ， 下 次 需要 处 理 时 需 重 新 加 入 epoll 





而 data 成 员 是 一 个 epoll_data 联 合 ， 其 定义 如 下 。 





typedef union epoll data { 


void *ptr; 
int fd; 

Uint32_t U32; 
uint64_t u64; 


} epoll data t; 





可 见 ， 这 个 data 成 员 还 与 具体 的 使 用 方式 相关 。 例 如 ， 
ngx_epoll_module 和 模块 只 使 用 了 联合 中 的 ptr 成 员 ， 作 为 指 问 


ngx_connection_t 连 接 的 指针 。 
(3) epoll_wait 系 统 调用 


epoll_wait 在 C 库 中 的 原型 如 下 。 





int epoll wait(int epfd,struct epoll event* events,int maxevents,int timeout ) ; 





收集 在 epoll 监 控 的 事件 中 己 经 发 生 的 事件 ， 如 果 epoll 中 没有 任何 一 
个 事件 发 生 ， 则 最 多 等 待 tmeout 毫 秒 后 返回 。epollL_wait 的 返回 值 表 示 
当前 发 生 的 事件 个 数 ， 如 果 返 回 0， 则 表示 本 次 调用 中 没有 事件 发 生 
如 果 返 回 -1， 则 表示 出 现 错误 ， 需 要 检查 errno 错 误 码 判断 错误 类 型 。 第 
1 个 参数 epfd 是 epoll 的 描述 符 。 第 2 个 参数 events 则 是 分 配 好 的 epoll_event 
结构 体 数 组 ，epoll 将 会 把 发 生 的 事件 复制 到 events 数 组 中 (events 不 可 以 
是 空 指针 ， 内 核 只 负责 把 数据 复制 到 这 个 events 数 组 中 ， 不 会 去 帮助 我 
们 在 用 户 态 中 分 配 内 存 。 内 核 这 种 做 法 效率 很 蜗 ) 。 第 3 个 参数 
maxevents 表 示 本 次 可 以 返回 的 最 大 事件 数目 ， 通 常 maxevents 参 数 与 巴 
分 配 的 events 数 组 的 大 小 是 相等 的 。 第 4 个 参数 timeout 表 示 在 没有 检测 到 
事件 发 生 时 最 多 等 待 的 时 间 (单位 为 毫秒 )， 如 果 timeout 为 0， 则 表示 
epoll_wait 在 rdllist 链 表 中 为 衬 ， 立 刻 返 回 ， 不 会 等 竺 。 

















epoll 有 两 种 工作 模式 : LT 水 平 触发 ) 模式 和 ET《〈 边 缘 触及 ) 模 
式 。 默 认 情 况 下 ，epoll 采 用 LT 模式 工作 ， 这 时 可 以 处 理 阻 暑 和 非 阻 嗓 


套 接 字 ， 而 表 9-3 中 的 EPOLLET 表 示 可 以 将 一 个 事件 改 为 ET 模式 。ET 模 
式 的 效率 要 比 LT 模 式 高 ， 它 只 支持 非 阻塞 套 接 字 。ET 模 式 与 LT 模式 的 
区 别 在 于 ， 当 一 个 新 的 事件 到 来 时 ，ET 模 式 下 当然 可 以 从 epoll_wait 调 

用 中 获取 到 这 个 事件 ， 可 是 如 果 这 次 没有 把 这 个 事件 对 应 的 套 接 字 缓冲 
区 处 理 完 ， 在 这 个 套 接 字 没 有 新 的 事件 再 次 到 来 时 ， 在 ET 模式 下 是 无 

法 再 次 从 epoll_wait 调 用 中 获取 这 个 事件 的 ， 而 LT 模式 则 相反 ， 只 要 一 

个 事件 对 应 的 套 接 字 缓 冲 区 还 有 数据 ， 就 总 能 从 epoll_wait 中 获取 这 个 

事件 。 因 此 ， 在 LI 模式 下 开发 基于 epol 的 应 用 要 简单 一 些 ， 不 太 容 易 

出 错 ， 而 在 ET 模式 下 事件 发 生 时 ， 如 果 没 有 彻底 地 将 缓冲 区 数据 处 理 

完 ， 则 会 导致 缓冲 区 中 的 用 户 请 求 得 不 到 响应 。 默 认 情 况 下 ，Nginx 是 

通过 ET 模式 使 用 epol 的 ， 在 下 文中 就 可 以 看 到 相关 内 容 。 











9.6.3 ngx_epoll _ module 模块 的 实现 





本 节 主 要 介绍 事件 驱动 模块 接口 与 eppoll 用 法 是 如 何 结合 起 来 发 挥 作 
用 的 。 首 先 看 一 下 ngx_epoll_module 模 块 究竟 对 哪些 配置 项 感 兴 趣 ， 其 
中 ngx_epoll_commands 数 组 指明 了 影响 其 可 定制 性 的 两 个 配置 项 。 


static ngx_command t ngx_ epoll commands[] = { 
/在 调用 





epo1l1_wait 时 ， 将 由 第 


2 和 第 


3 个 参数 告诉 


Linux 内 核 一 次 最 多 可 返回 多 少 个 事件 。 这 个 配置 项 表示 调用 一 次 


epoll wait 时 最 多 可 以 返回 的 事件 数 ， 当 然 ， 它 也 会 预 分 配 那 么 多 


epoll_event 结 构 体 用 于 存储 事件 





*/ 

{ ngx_string("epoll events"), 
NGX_EVENT_CONF |NGX_CONF_TAKE1., 
ngx_conf_set_num_slot, 

0, 
offsetof(ngx_epoll conf_t, events), 
NULL }, 
/指明 在 开启 异步 
I/0 且 使 用 


io_setup 系 统 调用 初始 化 异步 


I/0 上 下 文 环境 时 


/初始 分 配 的 异步 


I/0 事 件 个 数 ， 详 见 


9.9 节 


A 
{ ngx_string("worker_aio_requests"), 

NGX_EVENT_CONF |NGX_CONF_TAKE1., 
ngx_conf_set_num_slot, 
0, 
offsetof(ngx_epoll] conf_t, aio_requests), 
NULL }, 
ngx_null_ command 








}; 





上 面 使 用 了 预 分 配 的 ngx_conf_set_num_slot 方 法 来 解析 这 两 个 配置 
项 ， 下 面 看 一 下 存储 配置 项 的 结构 体 ngx_epoll_conf t。 





ngx_epoll conf_t。 


typedef struct { 
ngx_uint_t events; 
ngx_uint_t aio_requests,; 
} ngx_epoll] conf_t; 





其 中 ，events 是 调用 epoll_wait 方 法 时 传 入 的 第 3 个 参数 maxevents， 
而 第 2 个 参数 events 数 组 的 大 小 也 是 由 它 决定 的 ， 下 面 将 在 ngx_epoll_init 
方法 中 初始 化 这 个 数组 。 


接 下 来 看 一 下 epoll 是 如 何 定义 ngx_event_module_t 事 件 模块 接口 
的 ， 代 码 如 下 。 





static ngx_str_t epoll name = ngx_string("epoll"); 
ngx_event_module _t ngx_epoll module ctx = { 
&epoll name, 
ngx_epoll create_conf, 
ngx_epoll_ init_conf, 








// 对 应 于 


ngx_event_actions_t 中 的 


add 方 法 


ngx_epoll add_event, 
// 对 应 于 


ngx_event_actions_t 中 的 


de 方法 


ngx_epoll del event, 
// 对 应 于 


ngx_event_actions_t 中 的 


enable 方 法 , 与 


add 方 法 一 至 


ngx_epoll add_event, 
// 对 应 于 


ngx_event_actions_t 中 的 


disable 方 法 , 与 


del] 方 法 一 至 


ngx_epoll del event, 
// 对 应 于 


ngx_event_actions_t 中 的 


add_conn 方 法 


ngx_epoll add_connection, 
XA/ 对 应 于 


ngx_event_actions_t 中 的 


del_conn 方 法 


ngx_epoll del connection, 
// 未 实现 


ngx_event_actions_t 中 的 


process_changes 方 法 


NULL, 
// 对 应 于 


ngx_event_actions_t 中 的 


process_events 方 法 


ngx_epoll_ process_ events, 
// 对 应 于 


ngx_event_actions_t 中 的 


init 方 法 


ngx_epoll_ init, 
// 对 应 于 


ngx_event_actions_t 中 的 


done 方 法 


ngx_epol1_done， 





其 中 ，ngx_epoll_create_conf 方 法 和 ngx_epoll_init_conf 方 法 只 是 为 
了 解析 配置 项 ， 略 过 不 提 ， 下 面 重 点 看 一 下 ngx_event_actions_t 中 的 10 
个 接口 是 如 何 实现 的 。 


首先 从 实现 init 接 口 的 ngx_epoll_init 方 法 讲 起 。ngx_epoll-init 方 法 是 
在 什么 时 候 被 调用 的 呢 ? 在 图 9-4 的 第 4 步 中 它 会 被 调用 ， 也 承 是 Nginx 
的 启动 过 程 中 。ngx_epoll_init 方 法 主要 做 了 两 件 事 : 





1) 调用 epoll_create 方 法 创建 epoll 对 象 。 


2) 创建 event_list 数 组 ， 用 于 进行 epoll_wait 调 用 时 传递 内 核 态 的 事 
件 。 


event_list 数 组 就 是 用 于 在 epoll_wait 调 用 中 接收 事件 的 参数 ， 如 下 所 


修 。 





static int ep = -1; 
static struct epoll event *event list; 
static ngx_uint_t nevents; 





其 中 ，ep 是 epoll 对 象 的 描述 符 ，nevents 是 上 面 说 到 的 epoll_events 配 
置 项 参数 ， 它 既 指明 了 epoll_wait 一 次 返回 的 最 大 事件 数 ， 也 告诉 了 
event_list 应 该 分 配 的 数组 大 小 。ngx_epoll_init 方 法 代码 如 下 所 示 。 





static ngx_int_t ngx_epoll init(ngx_cycle t *cycle, ngx_msec t timer) 





ngx_epoll conf_t *epcf; 
/* 获 取 


create_conf 中 生成 的 


ngx_epoll_conf_t 结 构 体 ， 它 已 经 被 赋予 解析 完 配 置 文件 后 的 值 。 详 细 内 容 可 参见 


9.4.1 节 中 关于 


ngx_event_get_conf 宏 的 用 法 


大 
/ 
epcf = ngx_event_ get_ conf(cycle->conf_ctx, ngx_epoll module); 
if (ep == -1) { 
/* 调 用 


epo1l1_create 在 内 核 中 创建 


epol1L1 对 象 。 上 文 已 经 讲 过 ， 参 数 


Size 不 是 用 于 指明 





epoll 能 够 处 理 的 最 大 事件 个 数 ， 因 为 在 许多 


Linux 内 核 版 本 中 ， 


epoll 是 不 处 理 这 个 参数 的 ， 所 以 设 为 


cycle-> connection_n/2 (而 不 是 


cycle->connection_n) 也 不 要 紧 


*/ 
ep = epoll create(cycle->connection_n/2); 
if (ep == -1) { 
ngx_log_error(NGX_LOG_ EMERG, cycle->log, ngx_errno, 
"epoll create() failed"); 
return NGX_ERROR,; 
} 
#if (NGX_HAVE_FILE_AIO) 
// 异步 


I/0 内 容 可 参见 


ngx_epoll aio_init(cycle, epcf); 
#endif 
} 


if (nevents < epcf->events) { 
if (event list) { 
ngx_free(event_list); 


} 
// 初始 化 


event_1List 数 组 。 数 组 的 个 数 是 配置 项 


epol11_events 的 参数 


event_list = ngx_alloc(sizeof(struct epoll event) * epcf->events, Cycle->]10( 
if (event_list == NULL) { 

return NGX_ERROR,; 
} 


// nevents 也 是 配置 项 


epoll_events 的 参数 


nevents 


= epcf->events,; 
// 指明 读 写 


I/0 的 方法 ， 本 章 不 做 具体 说 明 


ngx_io = ngx_os_io; 
// 设置 


ngx_event_actions 接 口 


ngx_event_actions = ngx_epoll module ctx.actions,; 


#if (NGX_ HAVE_ CLEAR_ EVENT) 
/* 默 认 是 采用 





ET 模式 来 使 用 


epol1l1 的 ， 


NGX_USE_CLEAR_EVENT 宏 实际 上 就 是 在 告诉 


Nginx 使 用 


ET 模式 


4 
ngx_event_flags = NGX_USE_CLEAR_EVENT 
#else 
ngx_event_flags = NGX_USE_LEVEL_EVENT 
#endif 
|NGX_USE_GREEDY_EVENT 
|NGX_USE_EPOLL_EVENT ， 
return NGX_OK， 





ngx_event_actions 是 在 Nginx 事 件 框架 处 理事 件 时 封 疙 的 接口 ， 我 们 
会 在 9.8 节 中 说 明 它 的 用 法 。 


对 于 epoll 而 言 ， 并 没有 enable 事 件 和 disable 事 件 的 概念 ， 另 外 ， 从 
ngx_epoll_ module_ctx 结 构 体 中 可 以 看 出 ，enable 和 add 接 口 都 是 使 用 
ngx_epoll_add_event 方 法 实现 的 ， 而 disable 和 del 接 口 都 是 使 用 


ngX_epoll_del_event 方 法 实现 的 。 下 面 以 ngx_epoll_add_event 方 法 为 例 介 
绍 一 下 它们 是 如 何 调用 epoll_ctl 向 epoll 中 添加 事件 或 从 epoll 中 删除 事件 
的 5 





static ngx_int_t 
ngx_epoll add event(ngx_ event _t *ev, ngx_int _t event, ngx_uint_t flags) 


int op; 

uint32_t events, prev; 
ngx_event_t *e) 
ngx_connection_t CG 


struct epoll event ee; 
// 每 个 事件 的 





data 成 员 都 存放 着 其 对 应 的 


ngx_connection_t 连 接 


c = ev->data,; 
/* 下 面 会 根据 


event 参 数 确定 当前 事件 是 读 事件 还 是 写 事件 ， 这 会 决定 
events 是 加 上 

EPOLLIN 标 志 位 还 是 

EPOLLOUT 标 志 位 

*/ 


events = (uint32 _t) event,; 


// 根据 





active 标 志 位 确定 是 否 为 活路 事件， 以 决定 到 底 是 修改 还 是 添加 事件 


if (e->active) { 
op = EPOLL_CTL_MOD ， 


} else { 

op = EPOLL_CTL_ADD; 
} 
// 加 入 


flags 参 数 到 


events 标 志 位 中 


ee.events = events | (uint32 t) flags; 
/*ptr 成 员 存 储 的 是 


ngx_connection_t 连 接 ， 可 参见 
9.6.2 节 中 
epo11 的 使 用 方式 。 在 


9.2 节 中 曾经 提 到 过 事件 的 





instance 标 志 位 ， 下 面 就 配合 
ngx_epoll_process_events 方 法 说 明 它 的 用 法 


WA 
ee.data.ptr = (void *) ((uintptr_t) c | ev->instance); 
// 调用 


epoll_ctl 方 法 向 
epo1ll1 中 添加 事件 或 者 在 


ep0o1ll 中 修改 事件 


if (epoll ctl(ep, op, c->fd, &ee) == -1) { 
ngx_1log_error(NGX_ LOG ALERT, ev->1l0g, ngx_errno, 
"epoll ctl(%d, %d) failed", op, c->fd); 
return NGX_ERROR,; 


} 
// 将 事件 的 


active 标 志 位 置 为 


1， 表 示 当 前 事件 是 活跃 的 





ev->active = 1; 
return NGX_OK， 








ngx_epoll_del_event 方 法 也 通过 epoll_ctl 删 除 epoll 中 的 事件 ， 具 体 代 
码 这 里 不 再 罗列 ， 读 者 可 参照 ngx_epoll_add_event 的 实现 理解 其 意义 。 


对 于 ngx_epoll_add_connection 方 法 和 ngx_epoll_del connection 方 
法 ， 也 是 调用 epoll_ctl 方 法 向 epoll 中 添加 事件 或 者 在 epoll 中 删除 事件 
的 ， 只 是 每 一 个 连接 都 对 应 读 / 写 事件 。 因 此 ，ngx_epoll_add_connection 
方法 和 ngx_epoll_del_connection 方 法 在 每 次 执行 时 也 都 是 同时 将 每 个 连 
接 对 应 的 读 、 写 事件 active 标 志 位 置 为 1 的 ， 这 里 将 不 再 给 出 其 代码 。 


对 于 事件 的 instance 标 志 位 ， 己 经 在 9.2 节 中 简单 地 介绍 了 它 的 意 
义 ， 下 面 将 结合 ngx_epoll_process_events 方 法 具体 说 明 其 意义 。 
ngx_epoll_process_events 是 实现 了 收集 、 分 发 事件 的 process_events 接 口 
的 方法 ， 其 主要 代码 如 下 所 示 。 








static ngx_int_t ngx_epoll process events(ngx_cycle t *cycle, ngx_msec_t timer, ngx_ 


{ 





int events,; 

uint32_t revents,; 

ngx_int_t instance, i; 
ngx_event_t *rev, *wev, **queue,; 
ngx_connection t *c; 

/* 调 用 


epoll_ wait 获取 事件 。 注 意 ， 


timer 参 数 是 在 
process_events 调 用 时 传 入 的 ， 在 
9.7 和 

9.8 节 中 会 提 到 这 个 参数 


*/ 
events = epoll wait(ep, event_ list, (int) nevents, timer); 


9.7 节 中 会 介绍 
Nginx 对 时 间 的 缓存 和 管理 。 当 
flags 标 志 位 指示 要 更 新 时 间 时 ， 就 是 在 这 里 更 新 的 


4 
If (flags & NGX UPDATE_ TIME || ngx_event timer alarm) { 
// 更 新 时 间 ， 参 见 


9.7.1 节 


ngx_time_update(); 


// 遍历 本 次 


epol1_wait 和 返回 的 所 有 事件 





for (i = 0; i < events; i++) { 
/* 对 照 着 上 面 提 到 的 


ngx_epoll_add_event 方 法 ， 可 以 看 到 


ptr 成 员 就 是 


ngx_connection_t 连 接 的 地 址 ， 但 最 后 


1 位 有 特殊 含义 ， 需 要 把 它 屏 项 掉 


c = event_ list[i].data.ptr; 
// 将 地 址 的 最 后 一 位 取出 来 ， 用 


Instance 变 量 标识 


instance = (uintptr_t) c & 1; 
/* 无 论 是 


32 位 还 是 


64 位 机 器 ， 其 地 址 的 最 后 


1 位 肯定 是 


09， 可 以 用 下 面 这 行 语句 把 


ngx_connection tt 的 地 址 还 原 到 真正 的 地 址 值 





*/ 
c= (ngx_connection t *) ((uintptr_t) c & (uintptr_t) ~1); 
// 取出 读 事件 
rev = c->read; 
// 判断 这 个 读 事件 是 否 为 过 期 事件 
If (c->fd == -1 || rev->instance != instance) { 
AX* 当 
fd 套 接 字 描 述 符 为 
= 或 者 


instance 标 志 位 不 相等 时 ， 表 示 这 个 事件 已 经 过 期 了 ， 不 用 处 理 


*/ 


continue; 





} 
// 取出 事件 类 型 


revents = event_ list[i].events,; 








// 如 果 是 读 事 件 且 该 事件 是 活跃 的 


If ((revents & EPOLLIN) && rev->active) { 


// flags 参 数 中 含有 


NGX_POST_EVENTS 表 示 这 批 事件 要 延 后 处 理 


if (flags & NGX_POST_EVENTS) { 
/* 如 果 要 在 


post 队 列 中 延 后 处 理 该 事件 ， 首 先 要 判断 它 是 新 连接 事件 还 是 普通 事件 ， 以 决定 把 它 加 入 到 


ngx_posted_accept_events 队 列 或 者 





ngx_posted_events 队 列 中 。 关 于 


post 队 列 中 的 事件 何 时 执行 ， 可 参见 





queue = (ngx_event t **) (rev->accept &ngx_posted accept _ events : 





// 将 这 个 事件 添加 到 相应 的 延 后 执行 队列 中 


ngx_locked_post_event(rev, queue); 
} else { 
// 立即 调用 读 事件 的 回调 方法 来 处 理 这 个 事件 





rev->handler (rev); 


// 取出 写 事 件 


wev = c->write; 
if ((revents & EPOLLOUT) && wev->active) { 
// 判断 这 个 读 事件 是 否 为 过 期 事件 


if (c->fd == -1 || wev->instance != instance) { 
/* 当 


fd 套 接 字 描 述 符 为 
-1 或 者 
instance 标 志 位 不 相等 时 ， 表 示 这 个 事件 已 经 过 期 了 ， 不 用 处 理 


*/ 
continue; 


if (flags & NGX_POST_EVENTS) { 
// 将 这 个 事件 添加 到 


post 队 列 中 延 后 处 理 


ngx_locked_ post_event(wev, &ngx_posted events); 
} else { 


// 立即 调用 这 个 写 事件 的 回调 方法 来 处 理 这 个 事件 


wev->handler (wev); 


return NGX_OK; 





ngx_epoll_process_events 方 法 会 收集 当前 触发 的 所 有 事件 ， 对 于 不 


需要 加 入 到 post 队 列 延 后 处 理 的 事件 ， 该 方法 会 立刻 执行 它们 的 回调 方 
法 ， 这 其 实 是 在 做 分 发 事件 的 工作 ， 只 是 它 会 在 自己 的 进程 中 调用 这 些 
回调 方法 而 已 ， 因 此 ， 每 一 个 回调 方法 都 不 能 导致 进程 休眠 或 者 消耗 太 
多 的 时 间 ， 以 免 epol 不 能 即时 地 处 理 其 他 事件 。 





instance 标 志 位 为 什么 可 以 判断 事件 是 否 过 期 ? 从 上 面 的 代码 可 以 
看 出 ，instance 标 志 位 的 使 用 其 实 很 简单 ， 它 利用 了 指针 的 最 后 一 位 一 
定 是 0 这 一 特性 。 既 然 最 后 一 位 始终 都 是 9， 那么 不 如 用 来 表示 
instance。 这 样 ， 在 使 用 ngx_epoll_add_event 方 法 向 epoll 中 添加 事件 时 ， 
就 把 epoll_event 中 联合 成 员 data 的 ptr 成 员 指 向 ngx_connection_t 连 接 的 地 
址 ， 同 时 把 最 后 一 位 置 为 这 个 事件 的 instance 标 志 。 而 在 
ngx_epoll_process_events 方 法 中 取出 指向 连接 的 ptr 地 址 时 ， 先 把 最 后 一 
位 instance 取 出 来 ， 再 把 ptr 还 原 成 正常 的 地 址 赋 给 ngx_connection_t 连 
接 。 这 样 ，instance 究 竟 放 在 何 处 的 问题 也 就 解决 了 。 


那么 ， 过 期 事件 又 是 怎么 回 事 呢 ? 举 个 例子 ， 假 设 epoll_wait 一 次 
返回 3 个 事件 ， 在 第 1 个 事件 的 处 理 过 程 中 ， 由 于 业务 的 需要 ， 所 以 关闭 
了 一 个 连接 ， 而 这 个 连接 恰好 对 应 第 3 个 事件 。 这 样 的 话 ， 在 处 理 到 第 3 
个 事件 时 ， 这 个 事件 就 已 经 是 过 期 事件 了 ， 一 旦 处 理 必 然 出 错 。 既 然 如 
此 ， 把 关闭 的 这 个 连接 的 fd 套 接 字 置 为 -1 能 解决 问题 吗 ? 答案 是 不 能 处 
理 所 有 情况 。 


下 面 先 来 看 看 这 种 貌似 不 可 能 发 生 的 场景 到 底 是 怎么 发 生 的 : 假设 


第 3 个 事件 对 应 的 na 中 的 fd 僚 接 字 原 先是 50， 处 理 第 1 
个 事件 时 把 这 个 连接 的 套 接 字 关 闭 了， 同时 置 为 -1， 并 且 调 用 
ngx_free_connection 将 该 连接 归还 给 连接 池 。 在 ngx_epoll_process_events 
方法 的 循环 中 开始 处 理 第 2 个 事件 ， 恰 好 第 2 个 事件 是 建立 新 连接 事件 ， 
调用 ngx_get_connection 从 连接 池 中 取出 的 连接 非常 可 能 就 是 刚刚 释放 的 
第 3 个 事件 对 应 的 连接 。 由 于 套 接 字 50 刚 刚 被 释放 ，Linux 内 核 非 常 有 可 

能 把 刚刚 释放 的 套 接 字 50 又 分 配给 新 建立 的 连接 。 因 此 ， 在 循环 中 处 理 
第 3 个 事件 时 ， 这 个 事件 就 是 过 期 的 了 ! 它 对 应 的 事件 是 关闭 的 连接 ， 
而 不 是 新 建立 的 连接 。 








如 何 解 决 这 个 问题 ? 依靠 instance 标志 位 。 当 调用 
ngx_get_connection 从 连接 池 中 获取 一 个 新 连接 时 ，instance 标 志 位 就 会 
置 反 ， 代 码 如 下 所 示 。 





ngx_connection t * 
ngx_get_connection(ngx_socket t s, ngx_log_t *10g) 


{ 


// 从 连接 池 中 获取 一 个 连接 


ngx_connection t *c; 
c = ngx_cycle->free_connections 


rev = C->read 
wev = C->write 


instance = rev->instance 
// 将 


instance 标 志 位 置 为 原来 的 相反 值 


rev->instance = !instance,; 
wev->instance = !instance; 
return c; 


} 





这 样 ， 当 这 个 ngx_connection_t 连 接 重 复 使 用 时 ， 它 的 instance 标 志 
位 一 定 是 不 同 的 。 因 此 ， 在 ngx_epoll_process_events 方 法 中 一 旦 判断 
instance 发 生 了 变化 ， 就 认为 这 是 过 期 事件 而 不 予 处 理 。 这 种 设计 方法 
古 非 常 值得 读者 学 习 的 ， 因 为 它 几 乎 没有 增加 任何 成 本 束 很 好 地 解决 了 
服务 器 开发 时 一 定 会 出 现 的 过 期 事件 问题 。 








目前 ， 在 ngx_event_actions_t 接 口中 ， 所 有 事件 模块 都 没有 实现 
process_changes 方 法 。done 接 口 是 由 ngx_epoll_done 方 法 实现 的 ， 在 
Nginx 退 出 服务 时 它 会 得 到 调用 。ngx_epoll_done 主 要 是 关闭 epoll 描 述 符 
ep， 同 时 释放 event_list 数 组 。 


了 解 了 ngx_epoll_module_ctx 中 所 有 接口 的 实现 后 ， 
ngx_epoll_module 模 块 的 定义 就 非常 简单 了 ， 如 下 所 示 。 








ngx_module t ngx epoll module = { 
NGX_MODULE_V1, 
&ngx_epoll module_ ctx, 
ngx_epoll commands, 
NGX_EVENT_MODULE， 
NULL, 


* module context */ 

* module directives */ 
* module type */ 

* init master */ 





i 


NULL, /* init module */ 
NULL， /* init process */ 
NULL, /* init thread */ 
NULL, /* exit thread */ 
NULL， /* exit process */ 
NULL /* exit master */ 


了 
NGX_MODULE_V1_PADDING 








这 里 不 需要 再 实现 ngx_module_t 接 口中 的 7 个 回调 方法 了 。 





至 此 ， 我 们 完整 地 介绍 了 ngx_epoll_module 模 块 是 如 何 实现 事件 驱 
动机 制 的 内 容 的 。 事 实 上 ， 其 他 事件 驱动 模块 的 实现 与 
ngx_epoll_module 模 块 的 差别 并 不 是 很 大 ， 读 者 可 以 参照 本 节 内 容 阅 读 
其 他 事件 模块 的 源 代码 。 


9.7 ”定时 器 事件 





Nginx 实 现 了 自己 的 定时 器 触发 机 制 ， 它 与 epoll 等 事件 驱动 模块 处 
理 的 网 络 事件 不 同 : 在 网 络 事件 中 ， 网 络 事件 的 触发 是 由 内 核 完成 的 ， 
内 核 如 果 支 持 epoll 就 可 以 使 用 ngx_epoll_module 模 块 驱动 事件 ， 内 核 如 
果 仅 支持 select 那 就 得 使 用 ngx_select_module 模 块 驱动 事件 ， 定 时 器 事件 
则 完全 是 由 Nginx 自 吴 实 现 的 ， 它 与 内 核 完 全 无 关 。 那 么 ， 所 有 事件 的 
定时 器 是 如 何 组 织 起 来 的 呢 ? 在 事件 超时 后 ， 定 时 器 是 如 何 触发 事件 的 
呢 ? 读 者 将 在 9.7.2 节 中 看 到 定时 器 事件 的 设计 ， 但 首先 需要 弄 清楚 
Nginx 的 时 间 是 如 何 管理 的 。Nginx 与 一 般 的 服务 器 不 同 ， 出 于 性 能 的 考 
虑 (不 需要 每 次 获取 时 间 都 调用 gettimeofday 方 法 ) ，Nginx 使 用 的 时 间 
是 缓存 在 其 内 存 中 的 ， 这 样 ， 在 Nginx 模 块 获取 时 间 时 ， 只 是 获取 内 存 
中 的 几 个 整 型 变量 而 已 。 这 个 缓存 的 时 间 是 如 何 更 新 的 呢 ? 又 是 在 什么 


时 刻 更 新 的 呢 ? 这 些 问题 读者 会 在 9.7.1 节 中 获得 答案 。 





























9.7.1 缓存 时 间 的 管理 








Nginx 中 的 每 个 进程 都 会 单独 地 管理 当前 时 间 ， 下 面 来 看 一 下 缓存 
的 全 局 时 间 变 量 是 什么 。ngx_time_t 结 构 体 是 缓存 时 间 变 量 的 类 型 ， 如 
下 所 示 。 














typedef struct { 
// 格林 威 治 时 间 


1970 年 


0 秒 到 当前 时 间 的 秒 数 


time_t sec; 
// sec 成 员 只 能 精确 到 秒 ， 


msec 则 是 当前 时 间 相对 于 


Sec 的 毫秒 偏 移 量 


ngx_uint_t msec 
// 时 区 


ngx_int_t gmtoff， 
} ngx_time_t; 





可 以 看 到 ，ngx_time t 是 精确 到 坚 秒 的 。 当 然 ，ngx_time {t 结 构 用 起 


来 并 不 是 那么 方便 ， 作 为 Web 服 务 器 ， 很 多 时 候 要 用 到 可 读 性 较 强 的 规 
范 的 时 间 字 符 串 ， 因 此 ，Nginx 定 义 了 以 下 全 局 变量 用 于 缓存 时 间 ， 代 


码 如 下 。 





// 格林 威 治 时 间 


1970 年 








1 月 


1 日 凌晨 


9 秒 到 当前 时 间 的 毫秒 数 


volatile ngx_msec_t ngx_current_msec 
// ngx_time _t 结 构 体 形式 的 当前 时 间 


volatile ngx_ time t *ngx_cached time; 
/用 于 记录 





error_1og 的 当前 时 间 字 符 串 ， 它 的 格式 类 似 于 : 


"1970/09/28 12:00:00"*/ 
volatile ngx_str_t ngx_cached err_log_ time; 
/* 用 于 





HTTP 相 关 的 当前 时 间 字 符 串 ， 它 的 格式 类 似 于 : 


"Mon, 28 Sep 1970 06:00:00 GMT"*/ 
volatile ngx_str_t ngx_cached_http_time; 
/* 用 于 记录 





HTTP 日 志 的 当前 时 间 字 符 串 ， 它 的 格式 类 似 于 : 


"28/Sep/1970:12:00:00 +0600"*/ 
volatile ngx_str_t ngx_cached http_log time,; 
// 以 





ISO 8601 标 准 格式 记录 下 的 字符 串 形式 的 当前 时 间 


volatile ngx_str_t ngx_cached http_ log iso08601; 








Nginx 为 用 户 提供 了 6 种 当前 时 间 的 表示 形式 ， 这 已 经 足够 用 了 。 


Nginx 绥 存 时 间 的 操作 方法 见 表 9-4 所 示 。 


表 9-4 Neginx 缓 存 时 间 的 操作 方法 


时 间 方 法 名 


void ngx_time_init(void); 


void ngx_time_update(void) 


u_char *ngx_http_time 
(u_char *buf, time tt) 


u_char *ngx http_cookie_ 
time(u_char *buf time tt) 


void ngx gmtime 
(time tt,ngx tm t *tp) 


时 间 方 法 名 


time tngx next time 


(time t when) 


#define ngx_time() 
ngx cached time->sec 


#define ngx_timeofdayO 


(ngx time t*)ngx cached time 





执行 意义 

初始 化 当前 进程 中 缓存 的 时 间 变 量 ， 同 
时 会 第 一 次 根据 gettimeofday 调用 刷新 组 
存 时 间 

使 用 gettimeofday 调用 以 系统 时 间 更 新 
缓存 的 时 间 ， 上 述 的 ngx_current_msec、 
ngx_cached time、 ngx cached err log_ 
time、 ngx cached http time、 ngx cached_ 
http_log time, ngx cached http log 
iso8601 这 6 个 全 局 变量 都 会 得 到 更 新 





t 是 需要 转换 的 时 间 ， 它 是 格 
林 威 治 时 间 1970 年 1 月 1 日 凌晨 | 将 时 间 t 转 换 成 “Mon, 28 Sep 1970 06:00:00 
0 点 0 分 0 秒 到 某 一 时 间 的 秒 数 , |GMT ”形式 的 时 间 ， 返 回 值 与 buf 是 相同 
buf 是 t 时 间 转 换 成 字符 串 形式 的 | 的 ， 都 是 指向 存放 时 间 的 字符 串 
HTTP 时 间 后 用 来 存放 字符 串 的 内 存 

t 是 需要 转换 的 时 间 ， 它 是 格 
林 威 治 时 间 1970 年 1 月 1 日 次 晨 | 将 时 间 t 转 换 成 “Mon, 28-Sep-70 06:00:00 
0 点 0 分 0 秒 到 某 一 时 间 的 秒 数 , |GMT” 形 式 适用 于 cookie 的 时 间 ， 返 回 值 
buf 是 t 时 间 转 换 成 字符 串 形式 适 | 与 buf 是 相同 的 ， 都 是 指向 存放 时 间 的 字 
用 于 cookie 的 时 间 后 用 来 存放 字 | 符 串 
符 串 的 内 存 

t 是 需要 转换 的 时 间 ， 它 是 格林 
威 治 时 间 1970 年 1 月 1 日 凌晨 0 
点 0 分 0 秒 到 某 一 时 间 的 秒 数 ，tp 
是 ngx_tm t 类 型 的 时 间 ， 实 际 上 
就 是 标准 的 tm 类 型 时 间 


将 时 间 t 转 换 成 ngx tm t 类 型 的 时 间 。 
下 面 会 说 明 ngx_tm_t 类 型 


( 续 ) 


执行 意义 

返回 -1 表示 失败 ， 和 否则 会 返回 : 中 如 果 
when 表示 当天 时 间 秒 数 ， 当 它 合并 到 实际 
时 间 后 ,已 经 超过 当前 时 间 ， 那么 就 返回 
when 合并 到 实际 时 间 后 的 秒 数 (相对 于 格 
when 表示 期 待 过 期 的 时 间 ， 它 | 林 威 治 时 间 1970 年 1 月 1 日 凌晨 0 点 0 分 
0 秒 到 某 一 时 间 的 秒 数 ); 

四 反之 ， 如 果 合 并 后 的 时 间 早 于 当前 时 
间 ， 则 返回 下 一 天 的 同一 时 刻 (当天 时 刻 ) 
的 时 间 。 它 目前 仅 具 有 与 expires 配置 项 相 
关 的 缓存 过 期 功能 


无 获取 到 格林 威 治 时 间 1970 年 1 月 1 日 凌 
晨 0 点 0 分 0 秒 到 当前 时 间 的 秒 数 


仅 表 示 一 天 内 的 秒 数 





ngx_tm_t 是 标准 的 tm 类 型 时 间 ， 下 面 先 看 一 下 tm 时 间 是 什么 样 的 ， 
代码 如 下 。 





Struct tm { 
// 秒 
- 取 值 区 间 为 
[9, 59] 
int tm_sec; 
// 分 
- 取 值 区 间 为 
[9, 59] 
int tm_min; 
// 时 
- 取 值 区 间 为 
[9, 23] 
int tm_hour; 
// 一 个 月 中 的 日 期 
- 取 值 区 间 为 
[1, 31] 
int tm_mday; 
ZX/ 月 你 (4 处 一 月 开始 ; 
0 代表 一 月 ) 
- 取 值 区 间 为 
[9, 11] 
int tm_mon; 
// 年 份 ， 其 值 等 于 实际 年 份 减 去 
1900 


int tm_ year; 
// 星期 


- 取 值 区 间 为 


[9,6] ， 其 中 


0 代表 星期 天 ， 


1 代表 星期 一 ， 依 此 类 推 


int tm _ wday; 
/* 从 每 年 的 


1 月 


1 日 开始 的 天 数 


- 取 值 区 间 为 


[9, 365] ， 其 中 


0 代表 


1 月 


1 日 ， 


1 代表 


1 月 


2 日 ， 依 此 类 推 


4 
int tm yday; 
/* 夏 令 时 标识 符 。 在 实行 夏令 时 的 时 候 ， 


tm_isdst 为 正 ; 不 实行 夏令 时 的 时 候 ， 


tm_isdst 为 


0; 在 不 了 解 情况 时 ， 


tm_isdst 为 负 


int tm_isdst,; 





ngx_tm_t 与 tm 用 法 是 完全 一 怪 的 ， 如 下 所 示 。 





typedef struct tm ngx_tm_t; 
#define ngx_tm_ sec tm_sec 
#define ngx_tm min tm_min 
#define ngx_tm_hour tm_hour 
#define ngx_tm mday tm_mday 
#define ngx_tm_mon tm_mon 
#define ngx_tm year tm_year 
#define ngx_tm wday tm_wday 
#define ngx_tm isdst tm_isdst 





可 以 看 到 ，ngx_tm_t 中 类 似 ngx_tm_sec 这 样 的 成 员 与 tm_sec 是 完全 
一 致 的 。 


这 个 缓存 时 间 什 么 时 候 会 更 新 呢 ? 对 于 worker 进 程 而 言 ， 除 了 
Nginx 局 动 时 更 新 一 次 时 间 外 ， 任 何 更 新 时 间 的 操作 都 只 能 由 
ngx_epoll_process_events 方 法 (参见 9.6.3 市 ) 执行 。 回 顾 一 下 
ngx_epoll_process_events 方 法 的 代码 ， 当 flags 参 数 中 有 
NGX_UPDATE_TIME 标 志 位 ， 或 者 ngx_event_timer_alarm 标 志 位 为 1 
时 ， 就 会 调用 ngx_time_update 方 法 更 新 缓存 时 间 。 


9.7.2 ”缓存 时 间 的 精度 


上 文 简单 地 介绍 过 缓存 时 间 的 更 新 策略 ， 它 是 与 


ngx_epoll_process_events 方 法 的 调用 频率 及 其 flag 参 数 相关 的 。 实 际 上 ， 
Nginx 还 提供 了 设置 更 新 缓存 时 间 频 率 的 功能 〈 也 就 是 至 少 每 隅 
timer_resolution 芝 秒 必 须 更 新 一 次 缓存 时 间 ) ， 通 过 在 nginx.conf 文 件 中 
的 timer_resolution 配 置 项 可 以 设置 更 新 的 最 小 频率 ， 这 样 就 保证 了 绥 存 
时 间 的 精度 。 


下 面 看 一 下 timer_resolution 是 如 何 起 作用 的 。 在 图 9-4 的 第 5 步 中 ， 
ngx_event_core_module 模 块 初始 化 时 会 使 用 setitimer 系 统 调用 告诉 内 核 
隔 timer_resolution 宫 秒 调用 一 次 ngx_timer_signal_handler 方 法 。 而 
ngx_timer_signal_handler 方 法 则 会 将 ngx_event_timer alarm 标志 位 设 为 
1， 这 样 一 来 ， 一 旦 调用 ngx_epoll_process_events 方 法 ， 如 果 间 隔 的 时 间 
超过 timer_resolution 坚 秒 ， 肯 和 客 会 更 新 缓存 时 间 。 


但 如 果 很 久 都 不 调用 ngx_epoll_process_events 方 法 呢 ? 例如 ， 远 超 
过 timer_resolution 毫 秒 的 时 间 内 ngx_epoll_process_events 方 法 都 得 不 到 调 
用 ， 那 时 间 精 度 如 何 保证 呢 ? 在 这 种 情况 下 ，Nginx 只 能 从 事件 模块 对 
ngx_event_actions 中 process_events 接 口 的 实现 来 保证 时 间 精 度 了 。 
process_events 方 法 的 第 2 个 参数 timer 表 示 收 集 事 件 时 的 最 长 等 待 时 间 。 
例如 ， 在 epoll 模 块 下 ， 这 个 timer 就 是 epoll_wait 调 用 时 传 入 的 超时 时 间 
参数 。 如 果 在 设置 了 timer resolution 后 ， 这 个 timer 参 数 就 是 -1， 它 表示 
如 果 epoll_wait 等 调用 检测 不 到 已 经 发 生 的 事件 ， 将 不 等 待 而 是 立刻 返 
回 ， 这 样 就 控制 了 时 间 精 度 。 当 然 ， 如 果 某 个 事件 消费 模块 的 回调 方法 











执行 时 占用 的 时 间 过 长 ， 时 间 精 度 还 是 难以 得 到 保证 的 。 


9.7.3 ”定时 器 的 实现 


定时 器 是 通过 一 棵 红 黑 树 实 现 的 。ngx_event_timer_rbtree 就 是 所 有 
定时 器 事件 组 成 的 红 黑 树 ， 而 ngx_event_timer_sentinel 就 是 这 棵 红 黑 树 
的 哨兵 节点 ， 如 下 所 示 。 





ngx_thread_ volatile ngx_rbtree t ngx_event timer_rbtree; 
static ngx_rbtree node t ngx_event_ timer_sentinel; 











这 棵 红 黑 树 中 的 每 个 节点 都 是 ngx_event_t 事 件 中 的 timer 成 员 ， 而 
ngx_rbtree_node_t 节 点 的 关键 字 束 是 事件 的 超时 时 间 ， 以 这 个 超时 时 间 
的 大 小 组 成 了 二 又 排序 树 ngx_event_timer rbtree。 这 样 ， 如 果 需 要 找 出 
最 有 可 能 超时 的 事件 ， 那 么 将 ngx_event_timer_rbtree 树 中 最 左边 的 节点 
取出 来 即 可 。 只 要 用 当前 时 间 去 比较 这 个 最 左边 节点 的 超时 时 间 ， 就 会 
知道 这 个 事件 有 没有 触发 超时 ， 如 果 还 没有 触发 超时 ， 那 么 会 知道 最 少 

还 要 经 过 多 少 毫 秒 满足 超时 条 件 而 触发 超时 。 先 看 一 下 定时 器 的 操作 方 
法 ， 见 表 9-5。 


表 9-5 定时 器 的 操作 方法 


方法 名 


ngx int tngx event timer init 


执行 意义 





切 始 化 定时 器 
(ngx_log t *log); 初始 化 定时 好 





找 出 红 黑 树 中 最 左边 的 节点 ， 如 果 它 的 超 
时 时 间 大 于 当前 时 间 ， 也 就 表明 目前 的 定时 
器 中 没有 一 个 事件 满足 触发 条 件 ， 这 时 返回 
无 这 个 超时 与 当前 时 间 的 差 值 ， 也 就 是 需要 经 
过 多 少 毫秒 会 有 事件 超时 触发 ;如果 它 的 超 
时 时 间 小 于 或 等 于 当前 时 间 ， 则 返回 0， 表 
示 定 时 器 中 已 经 存在 超时 需要 触发 的 事件 


jd , 检查 定时 需 中 的 所 有 事件 ， 按 照 红 黑 树 关 
void nex event expire ik a ede Se 
- . - 0 无 键 字 由 小 到 大 的 顺序 依次 调用 已 经 满足 超时 
imers(void): rT ER 

条 件 需 要 被 触发 事件 的 handler 回调 方法 


static ngx_inline void 


ngx msec tngx event find 





timer(void): 


ngx event del timer 从 定时 咒 中 移 除 一 个 事件 


(ngx event t *ev) 


ev 是 需要 操作 的 事件 ，timer 
的 单位 是 毫秒 ， 它 告诉 定时 器 事 添加 一 个 定时 器 事件 ， 超 时 时 间 为 timer 
件 ev 希 望 timer 毫秒 后 超时 ， 同 | 毫秒 


时 需要 回调 ev 的 handler 方法 


static ngx_inline Vold 
ngx event add timer(ngx_ 


event t *ev, ngx msec ttimer) 





事实 上 ， 还 有 两 个 宏 与 ngx_event_add_timer 方 法 和 
ngx_event_del_timer 方 法 的 用 法 是 完全 一 样 的 ， 如 下 所 示 。 





#define ngx_add timer ngx_event_add timer 
#define ngx_del timer ngx_event del timer 





从 表 9-5 可 以 看 出 ， 只 要 调用 ngx_event_expire_timers 方 法 就 可 以 触 
发 所 有 超时 的 事件 ， 在 这 个 方法 中 ， 循 环 调用 所 有 满足 超时 条 件 的 事件 
的 handler 回 调 方法 。 那 么 ， 多 久 调 用 一 次 ngx_event_expire_timers 方 法 
呢 ? 这 个 时 间 频 率 可 以 部 分 参照 ngx_event_find_timer 方 法 ， 因 为 
ngx_event_find_timer 会 告诉 用 户 下 一 个 最 近 的 超时 事件 多 久 后 会 及 生 。 





在 9.8.5 节 中 ， 读 者 会 看 到 ngx_event_expire_timers 究 竞 什么 时 候 会 被 


调用 。 


9.8 ”事件 张 动 框 洪 的 处 理 流 程 


本 节 开 始 讨论 事件 处 理 流 程 。 在 9.5.1 节 中 已 经 看 到 ， 图 9-4 的 第 12 
步 会 将 监听 连接 的 读 事件 设 为 ngx_event_accept 方 法 ， 在 第 13 步 会 把 监 
听 连 接 的 读 事 件 添加 到 ngx_epoll_module 事 件 驱 动 模块 中 。 这 样 ， 在 执 
行 hgx_epoll_process_events 方 法 时 ， 如 果 有 新 连接 事件 出 现 ， 则 会 调用 
ngX_event_accept 方 法 来 建立 新 连接 。 在 9.8.1 节 中 将 会 讨论 
ngx_event_accept 方 法 的 执行 流程 。 





当然 ， 建 并 连接 其 实 没 有 那么 简单 。Nginx 出 于 充分 及 挥 多 核 CPU 
架构 性 能 的 考虑 ， 使 用 了 多 个 worker 子 进程 监听 相同 端口 的 设计 ， 这 样 
多 个 子 进 程 在 accept 建 立新 连接 时 会 有 第 抢 ， 这 会 各 来 著名 的 “ 慰 群 ” 问 
上 题 ， 子 进程 数量 越 多 问题 越 明 显 ， 这 会 造成 系统 性 能 下 降 。 在 9.8.2 市 
中 ， 我 们 会 讲 到 在 建立 新 连接 时 Nginx 是 如 何 避 免 出 现 “ 惊 群 * 现 象 的 。 





为 外 ， 建 立 连接 时 还 会 涉及 负载 均衡 问题 。 在 多 个 子 进 程 搜 抢 处 理 
一 个 新 连接 事件 时 ， 一 定 只 有 一 个 worker 子 进程 最 终 会 成 功 建 并 连接 ， 
随后 ， 它 会 一 直 处 理 这 个 连接 直到 连接 关闭 。 那 么 ， 如 果 有 的 子 进程 
很 “勤奋 ”， 它 们 抢 关 建 并 并 处 理 了 大 部 分 连接 ， 而 有 的 子 进 程 则 “运气 
不 好 ””， 只 处 理 了 少量 连接 ， 这 对 多 核 CPU 染 构 下 的 应 用 是 很 不 利 的 ， 
因为 子 进程 间 应 该 是 平等 的 ， 每 个 子 进程 应 该 尽量 地 独占 一 个 CPU 核 








心 。 子 进程 间 负 载 不 均衡 ， 必 然 影响 整个 服务 的 性 能 。 在 9.8.3 节 中 ， 我 
们 会 看 到 Nginx 是 如 何 解决 负载 均衡 问题 的 。 


实际 上 ， 上 述 问 题 的 解决 离 不 开 Nginx 的 post 事 件 处 理 机 制 。 这 个 
post 事 件 是 什么 意思 呢 ? 它 表示 允许 事件 延 后 执行 。Nginx 设 计 了 两 个 
post 队 列 ， 一 个 是 由 被 触发 的 监听 连接 的 读 事 件 构成 的 
ngx_posted_accept_events 队 列 ， 男 一 个 是 由 普通 读 / 写 事件 构成 的 
ngx_posted_events 队 列 。 这 样 的 post 事 件 可 以 让 用 户 完成 什么 样 的 功能 
呢 ? 


将 epoll_wait 产 生 的 一 批 事件 ， 分 到 这 两 个 队列 中 ， 让 存放 着 新 连 
接 事件 的 ngx_posted_accept_events 队 列 优先 执行 ， 存 放 普 通 事件 的 
ngx_posted_events 队 列 最 后 执行 ， 这 是 解决 “ 惊 群 ” 和 负载 均衡 两 个 问 
题 的 关键 。 


:如果 在 处 理 一 个 事件 的 过 程 中 产生 了 另 一 个 事件 ， 而 我 们 希望 这 
个 事件 随后 执行 (不 是 立刻 执行 ) ， 就 可 以 把 它 放 到 post 队 列 中 。 在 


9.8.3 节 中 会 介绍 post 队 列 。 


我 们 在 9.8.5 节 中 将 本 章 的 网 络 事件 、 定 时 器 事件 进行 综合 考虑 ， 以 
说 明 ngx_process_events_and_timers 事 件 框架 执行 流程 是 如 何 把 连接 的 建 
立 、 事 件 的 执行 结合 在 一 起 的 。 


9.8.1 如 何 建立 新 连接 


上 文 提 到 过 ， 处 理 新 连接 事件 的 回调 函数 是 ngx_event_accept， 其 
原型 如 下 。 


void ngx_event accept(ngx_event_t *ev) 





下 面 简单 介绍 一 下 它 的 流程 ， 如 图 9-6 所 示 。 
下 面 对 流程 中 的 7 个 步骤 进行 说 明 。 


1) 首先 调用 accept 方 法 试图 建立 新 连接 ， 如 果 没 有 准备 好 的 新 连接 
事件 ，ngx_event_accept 方 法 会 直接 返回 


2) 设置 负载 均衡 阔 值 ngx_accept_disabled， 这 个 冰 值 是 进程 允许 的 
连接 数 的 1/8 减 去 空闲 连接 数 ， 它 的 具体 用 法 参见 9.8.3 贡 。 












1 ) 调 用 accep 访 法 建立 新 的 
TCP 连 接 


[成 功 建立 TCP 连 接 ] 


2) 设 置 负载 均衡 国 值 


ngx_accept_disabled 






3) 由 连接 池 中 获取 一 个 


ngx_connection_t 结 构 体 






4) 为 这 个 连接 
创建 内 存 池 


[available 标志 位 为 1] 


5 设置 新 过 按 套 按 他 


没有 新 连接 立 
[没有 新 连接 可 建立 ] 的 属性 





6) Ee Wee 到 





7) 调 用 监听 端口 上 ngx listening + 结构 体 的 
handler 方 法 处 理 新 连接 


[检查 监听 连接 读 事件 的 available 标 志 位 ] 








available 为 0] 





图 9-6 ”ngx_event_accept 方 法 建立 新 连接 的 流程 


3) 调用 ngx_get_connection 方 法 由 连接 池 中 获取 一 个 


ngx_connection_t 连 接 对 象 。 


4) 为 ngx_connection_t 中 的 pool 指 针 建 立 内 存 池 。 在 这 个 连接 释放 
到 空间 连接 池 时 ， 释 放 pool 内 存 池 。 


5) 设置 套 接 字 的 属性 ， 如 设 为 非 阻塞 套 接 字 。 


6) 将 这 个 新 连接 对 应 的 读 事件 添加 到 epoll 等 事件 驱动 模块 中 ， 这 
样 ， 在 这 个 连接 上 如 果 接 收 到 用 户 请 求 epoll_wait， 就 会 收集 到 这 个 事 
件 。 


7) 调用 监听 对 象 ngx_listening_t 中 的 handler 回 调 方 法 。 
ngx_listening_t 结 构 体 的 handler 回 调 方法 就 是 当 新 的 TCP 连 接 刚 刚 建立 完 
成 时 在 这 里 调用 的 。 


最 后 ， 如 果 监 昕 事件 的 available 标 志 位 为 1， 再 次 循环 到 第 1 步 ， 否 
则 ngx_event_accept 方 法 结束 。 事 件 的 available 标 志 位 对 应 着 multi_accept 
配置 项 。 当 available 为 1 时 ， 告 诉 Nginx 一 次 性 尽量 多 地 建立 新 连接 ， 它 
的 实现 原理 也 就 在 这 里 。 


9.8.2 ”如 何 解决 “ 惊 群 > 回 题 


只 有 打开 了 accept_mutex 锁 ， 才 可 以 解决 “ 尺 群 "问题 。 何 谓 “ 慰 
群 *”? 就 像 上 面 说 过 的 那样 ，master 进 程 开始 监听 Web 端 口 ，fork 出 多 个 
worker 子 进程 ， 这 些 子 进程 开始 同时 监听 同一 个 web 端口 。 一 般 情 况 
下 ， 有 多 少 CPU 核心 ， 就 会 配置 多 少 个 worker 子 进程 ， 这 样 所 有 的 
worker 子 进程 都 在 承担 着 Web 服 务 器 的 角色 。 在 这 种 情况 下 ， 就 可 以 利 
用 每 一 个 CPU 核心 可 以 并 发 工作 的 特性 ， 充 分 发 挥 多 核 机 器 的 “威力 ”。 
但 下 面 假定 这 样 一 个 场景 : 没有 用 户 连 入 服务 器 ， 某 一 时 刻 恰 好 所 有 的 
worker 子 进程 都 休眠 且 等 待 新 连接 的 系统 调用 《〈 如 epoll_wait) ， 这 时 有 
一 个 用 户 向 服务 器 发 起 了 连接 ， 内 核 在 收 到 TCP 的 SYN 包 时 ， 会 激活 所 
有 的 休眠 worker 子 进程 ， 当 然 ， 此 时 只 有 最 先 开始 执行 accept 的 子 进程 
可 以 成 功 建立 新 连接 ， 而 其 他 worker 子 进程 都 会 accept 失 败 。 这 些 accept 
失败 的 子 进程 被 内 核 唤醒 是 不 必要 的 ， 它 们 被 唤醒 后 的 执行 很 可 能 也 是 
多 余 的 ， 那 么 这 一 时 刻 它 们 占用 了 本 不 需要 占用 的 系统 资源 ， 引 发 了 不 
必要 的 进程 上 下 文 切 换 ， 增 加 了 系统 开销 。 





也 许 很 多 操作 系统 的 最 新 版 本 的 内 核 已 经 在 事件 驱动 机 制 中 解决 
了 “ 慰 群 ”问题 ， 但 Nginx 作 为 可 移植 性 极 高 的 Web 服 务 器 ， 还 是 在 目 号 
的 应 用 层面 上 较 好 地 解决 了 这 一 问题 。 既 然 “ 惊 群 ? 是 多 个 子 进 程 在 同一 
时 刻 监听 同一 个 端口 引起 的 ， 那 么 Nginx 的 解决 方式 也 很 简单 ， 它 规定 
了 同一 时 刻 只 能 有 唯一 一 个 worker 子 进程 监听 Web 端 口 ， 这 样 吏 不 会 友 
生 * 惊 群 " 了 ， 此 时 新 连接 事件 只 能 唤醒 唯一 正在 监听 端口 的 worker 子 进 


程 。 


可 是 如 何 限 制 在 某 一 时 刻 仅 能 有 一 个 子 进程 监听 Web 端 口 呢 ? 下面 
看 一 下 ngx_trylock_accept_mutex 方 法 的 实现 。 在 打开 accept_mutex 锁 的 
情况 下， 只 有 调用 ngx_trylock_accept_mutex 方 法 后 ， 当 前 的 worker 进 程 
才 会 去 试 着 监 昕 web 端口， 具体 实现 如 下 所 示 。 





ngx_int_t ngx_trylock_accept_mutex(ngx_cycle t *cycle) 


/* 使 用 进程 间 的 同步 锁 ， 试 图 获取 


accept_mutex 锁 。 注 意 ， 


ngx_shmtx_trylock 返 回 


1 表示 成 功 拿 到 锁 ， 返 回 


0 表示 获取 锁 失败 。 这 个 获取 锁 的 过 程 是 非 阻塞 的 ， 此 时 一 旦 锁 被 其 他 


WOrKer 子 进程 占用 ， 


ngx_shmtx_trylock 方 法 会 立刻 返回 ( 详 见 


14.8 节 ) 


*/ 
If (ngx_shmtx_trylock(&ngx_accept_ mutex)) { 
A* 如 果 获 取 到 


accept_mutex 锁 ,但 


ngx_accept_mutex_held 为 





1， 则 立刻 返回 。 





ngx_accept_mutex_held 是 一 个 标志 位 ， 当 它 为 


1 时 ， 表 示 当 前 进程 已 经 获取 到 锁 了 


办 


If (ngx_accept_mutex_held 
&& ngx_accept_events == 0 
&& !(ngx_event_flags & NGX_USE_RTSIG_EVENT ) ) 





// ngx_accept_mutex 锁 之 前 已 经 获取 到 了 ， 立 刻 返回 


return NGX_OK; 


} 
// 将 所 有 监听 连接 的 读 事件 添加 到 当前 的 





epoll 等 事件 驱动 模块 中 


If (ngx_enable accept_ events(cycle) == NGX_ ERROR) { 
/* 上 既然 将 监听 句柄 添加 到 事件 驱动 模块 失败 ， 就 必须 释放 





ngx_accept_mutex 锁 


*/ 
ngx_shmtx_unlock(&ngx_accept_mutex); 
return NGX_ERROR ， 
} 


/* 经 过 


ngx_enable_accept_events 方 法 的 调用 ， 当 前 进程 的 事件 驱动 模块 已 经 开始 监听 所 有 的 端口 ， 这 时 





ngx_accept_mutex_held 标 志 位 置 为 





工 ， 方 便 本 进程 的 其 他 模块 了 解 它 目前 已 经 获取 到 了 锁 





*/ 
ngx_accept_events = 0; 
ngx_accept_mutex_held = 1; 
return NGX_OK， 
} 
/* 如 果 


ngx_shmtx_trylock 返 回 


9， 则 表明 获取 


ngx_accept_mutex 锁 失败 ， 这 时 如 果 


ngx_accept_mutex_held 标 志 位 还 为 





1， 即 当前 进程 还 在 获取 到 锁 的 状态 ， 这 当然 是 不 正确 的 ， 需 要 处 理 


而 


要 把 


< 
if (ngx_accept_ mutex_held) { 
/*ngx_disable_accept_events 会 将 所 有 监听 连接 的 读 事件 从 事件 驱动 模块 中 移 除 








if (ngx_disable accept_ events(cycle) == NGX_ ERROR) { 
return NGX_ERROR,; 

} 

/在 没有 获取 到 


ngx_accept_mutex 锁 时 ， 必 须 把 


ngx_accept_mutex_held 置 为 





0*/ 
ngx_accept_mutex_held = 0; 





} 
return NGX_OK; 
} 





在 上 面 关 于 ngx_trylock_accept_mutex 方 法 的 源 代码 中 ， 
ngx_accept_mnutex 实 际 上 是 Nginx 进 程 间 的 同步 锁 。 第 14 章 我 们 会 详细 介 
绍 进程 间 的 同步 方式 ， 目 前 只 需要 清楚 ngx_shmtx_trylock 方 法 是 一 个 非 
阻塞 的 获取 锁 的 方法 即 可 。 如 有 果 成 功 获取 到 锁 ， 则 返回 1， 侣 则 返回 0。 
ngx_shmtx_unlock 方 法 负责 释放 锁 。ngx_accept_mutex_held 是 当前 进程 
的 一 个 全 局 变量 ， 如 果 为 1， 则 表示 这 个 进程 已 经 获取 到 了 
ngx_accept_mnutex 锁 ， 如 果 为 0， 则 表示 没有 获取 到 锁 ， 这 个 标志 位 主要 
用 于 进程 内 各 模块 了 解 是 人 否 获取 到 了 ngx_accept_mnutex 锁 ， 具 体 定 义 如 
下 所 示 。 








ngx_shmtx_t ngx_accept_mutex; 
ngx_uint_t ngx_accept_mutex_held; 








此 ， 在 调用 ngx_trylock_accept_mutex 方 法 后 ， 要 么 是 唯一 获取 到 
ngx_accept_mutex 锁 有 其 epoll 等 事件 驱动 模块 开始 监控 Web 端 口上 的 新 
连接 事件 ， 要 么 是 没有 获取 到 锁 ， 当 前 进程 不 会 收 到 新 连接 事件 。 


如 果 ngx_trylock_accept_mutex 方 法 没有 获取 到 锁 ， 接 下 来 调用 事件 
驱动 模块 的 process_events 方 法 时 只 能 处 理 已 有 的 连接 上 的 事件 ， 如 果 获 
取 到 了 锁 ， 调 用 process_events 方 法 时 就 会 既 处 理 已 有 连接 上 的 事件 ， 也 
处 理 新 连接 的 事件 。 这 样 的 话 ， 问 题 又 来 了 ， 什 么 时 候 释放 
ngx_accept_mnutex 锁 呢 ? 等 到 这 批 事件 全 部 执行 完 吗 ? 这 当然 是 不 可 取 
的 ， 因 为 这 个 worker 进 程 上 可 能 有 许多 活跃 的 连接 ， 处 理 这 些 连接 上 的 
事件 会 占用 很 长 时 间 ， 也 就 是 说 ， 会 有 很 长 时 间 都 没有 释放 
ngx_accept_mnutex 锁 ， 这 样 ， 其 他 worker 进 程 就 很 难得 到 处 理 新 连接 的 
机 会 。 








如 何 解 决 长 时 间 占 用 ngx_accept_mnutex 锁 的 问题 呢 ? 这 就 要 依靠 
ngX_posted_accept_events 队 列 和 ngx_posted_events 队 列 了 。 首 先 看 下 面 
这 段 代 码 : 





if (ngx_trylock_accept_mutex(cycle) == NGX_ERROR) { 
return 
} 


If (ngx_accept_mutex_held) { 
flags |= NGX_POST_EVENTS; 








调用 ngx_trylock_accept_mutex 试 图 处 理 监听 端口 的 新 连接 事件 ， 如 


果 ngx_accept_mutex_held 为 1， 就 表示 开始 处 理 新 连接 事件 了 ， 这 时 将 
flags 标 志 位 加 上 NGX_POST_EVENTS。 这 里 的 flags 是 在 9.6.3 节 中 列举 
的 ngx_epoll_process_events 方 法 中 的 第 3 个 参数 flags。 回 顾 一 下 这 个 方法 
中 的 代码 ， 当 flags 标 志 位 包含 NGX_POST_EVENTS 时 是 不 会 立刻 调用 
事件 的 handler 回 调 方法 的 ， 代 码 如 下 所 示 。 





if ((revents & EPOLLIN) && rev->active) { 
if (flags & NGX_POST_EVENTS) { 
queue = (ngx_event t **) (rev->accept &ngx_posted accept_ events : &ngx_post 
ngx_locked_ post_event(rev, queue); 
} else { 
rev->handler (rev); 


} 





} 





对 于 写 事件 ， 也 可 以 采用 同样 的 处 理 方法 。 实 际 上 ， 
ngX_posted_accept_events 队 列 和 ngx_posted_events 队 列 把 这 批 事件 归 类 
了 ， 即 新 连接 事件 全 部 放 到 ngx_posted_accept_events 队 列 中 ， 普 通 事件 
则 放 到 ngx_posted_events 队 列 中 。 这 样 ， 接 下 来 会 先 处理 
ngx_posted_accept_events 队 列 中 的 事件 ， 处 理 完 后 就 要 立刻 释放 
ngx_accept_mutex 锁 ， 接 着 再 处 理 ngx_posted_events 队 列 中 的 事件 ( 参 
见 图 9-7) ， 这 样 就 大 大 减少 了 ngx_accept_mutex 锁 占用 的 时 间 。 





9.8.3 如何 实现 负载 均衡 


与 “ 惊 群 ?问题 的 解决 方法 一 样 ， 只 有 打开 了 accept_mutex 锁 ， 才 能 
实现 worker 子 进程 间 的 负载 均衡 。 在 图 9-6 的 第 2 步 中 ， 初 始 化 了 一 个 全 


局 变量 ngx_accept_disabled， 它 就 是 负载 均衡 机 制 实现 的 关键 闵 值 ， 实 
际 上 它 就 是 一 个 整 型 数据 。 





ngx_int_t ngx_accept_disabled; 





这 个 浆 值 是 与 连接 池 中 连接 的 使 用 情况 密切 相关 的 ， 在 图 9-6 的 第 
步 中 它 会 进行 赋值 ， 如 下 所 示 。 





ngx_accept_disabled = ngx_cycle->connection_n/8 
- Ngx_cycle->free_connection_n,; 





因此 ， 在 Nginx 启 动 时 ，ngx_accept_disabled 的 值 就 是 一 个 负数 ， 其 
值 为 连接 总 数 的 718。 其 实 ，ngx_accept_disabled 的 用 法 很 简单 ， 当 它 为 
负数 时 ， 不 会 进行 触发 负载 均衡 操作 ， 而 当 ngx_accept_disabled 是 正 数 
时 ， 就 会 触发 Nginx 进 行 负载 均衡 操作 了 。Nginx 的 做 法 也 很 简单 ， 就 是 
当 ngx_accept_disabled 是 正 数 时 当前 进程 将 不 再 处 理 新 连接 事件 ， 取 而 
代 之 的 仅仅 是 ngx_accept_disabled 值 减 1， 如 下 所 示 。 





If (ngx_accept_disabled > 0) { 
ngx_accept_disabled--; 
} else { 
If (ngx_trylock_accept_ mutex(cycle) == NGX_ERROR) { 
return; 


} 





上 面 这 段 代码 表明 ， 在 当前 使 用 的 连接 到 达 总 连接 数 的 78 时 ， 束 
不 会 再 处 理 新 连接 了 ， 同 时 ， 在 每 次 调用 process_events 时 都 会 将 
ngx_accept_disabled 减 1， 直 到 ngx_accept_disabled 降 到 总 连接 数 的 7/8 以 
下 时 ， 才 会 调用 ngx_trylock_accept_mutex 试 图 去 处 理 新 连接 事件 。 


此 ，Nginx 各 worker 子 进程 间 的 负载 均衡 仅 在 某 个 worker 进 程 处 理 
的 连接 数 达到 它 最 大 处 理 总 数 的 7/8 时 才 会 触发 ， 这 时 该 worker 进 程 就 会 
减少 处 理 新 连接 的 机 会 ， 这 样 其 他 较 空 亲 的 worker 进 程 就 有 机 会 去 处 理 
更 多 的 新 连接 ， 以 此 达到 整个 Web 服务 的 均衡 处 理 效 果 。 虽 然 这 样 的 机 
制 不 是 很 完美 ， 但 在 维护 一 定 程度 上 的 负载 均衡 时 ， 很 好 地 避免 了 当 某 
个 worker 进 程 由 于 连接 池 耗 尽 而 拒绝 服务 ， 同 时 ， 在 其 他 workerj 进 程 上 
处 理 的 连接 还 远 未 达到 上 限 的 问题 。 因 此 ，Nginx 将 accept_mutex 配 置 项 





默认 设 为 accept_mutex on。 


9.8.4 ” post 事件 队列 


上 文 已 经 介绍 过 post 事 件 的 意义 ， 本 节 来 看 一 下 post 事 件 处 理 的 实 
现 方 法 。 下 面 是 两 个 post 事 件 队列 的 定义 : 





ngx_thread_volatile ngx event t *ngx_posted accept_events,; 
ngx_thread volatile ngx event t *ngx_posted events,; 











这 两 个 指针 都 指向 事件 队列 中 的 首 个 事件 。 这 些 事件 间 是 以 双 同 链 


表 的 形式 组 织 成 post 事 件 队列 的 。 注 意 ，9.2 节 中 ngx_event_ t 结 构 体 的 
next 和 prev 成 员 仅 用 于 post 事 件 队列 。 


对 于 post 事 件 队列 的 操作 方法 共有 4 个 ， 见 表 9-6。 


在 9.6.3 节 中 己 经 介绍 过 ngx_post_event 方 法 的 应 用 ， 它 会 将 事件 添 
加 到 队列 中 ， 那 么 ，post 事 件 什 么 时 候 会 执行 呢 ? 在 9.8.5 节 我 们 就 会 介 
绍 ngx_event_process_posted 是 如 何 被 调用 的 。 


表 9-6 ”post 事 件 队 列 的 操作 方法 


方法 名 执行 意义 
ngx locked post_ event(ev, queue) | sy 是 要 深 加 到 Pot 事 件 队 列队 ,网 oe 件 区 天 到 添加 束 什 < 
事件 ，queue 是 post 事件 队列 意 ，ev 将 插入 到 事件 队列 的 首部 
ee 司 线程 安全 地 向 queue 事件 队列 中 添加 事 
ngx post_event(ev. queue) 家 六 ot 列 的 事件 ， 件 ev。 在 目前 不 使 用 多 线程 的 情况 下 ， 它 
人 与 ngx_locked_post_event 的 功能 是 相同 的 
ngx_delete_posted_event(ev) 本 下 po 将 0 
外 一 除 的 事件 删除 





cycle 是 进程 的 核心 结构 体 ngx_ 
void ngx_event_process_posted |cycle t 的 指针 ，posted 是 要 操作 的 | 调用 posted 事 件 队 列 中 所 有 事件 的 
(ngx_cycle_t *cycle,ngx_thread_|post 事件 队列 ， 它 的 取 值 目前 仅 可 | handler 回调 方法 。 每 个 事件 调用 完 handler 
volatile ngx_event t **posted): 以 为 ngx_posted_events 或 者 ngx_ | 方法 后 ,就 会 从 posted 事件 队列 中 删除 


posted_accept_events 


9.8.5 ”ngx_process_events_and_timers 流 程 


本 市 将 综合 上 文 相关 内 容 ， 探 讨 Nginx 事 件 框 架 处 理 的 流程 。 


在 图 8-7 中 ， 每 个 worker 进 程 都 在 ngx_worker_process_cycle 方 法 中 循 
环 处 理事 件 。 图 8-7 中 的 处 理 分 发 事件 实际 上 就 是 调用 的 


ngx_process_events_and_timers 方 法 ， 下 面 先 看 一 下 它 的 定义 : 





void ngx_process_ events and timers(ngx_cycle t *cycle); 





循环 调用 ngx_process_events_and_timers 方 法 就 是 在 处 理 所 有 的 事 
件 ， 这 正 是 事件 驱动 机 制 的 核心 。 顾 名 思 义 ， 
ngx_process_events_and_timers 方 法 既 会 处 理 普通 的 网 络 事 件 ， 也 会 处 理 
定时 右 事 件 ， 在 图 9-7 中 ， 读 者 会 看 到 在 这 个 方法 中 到 懈 做 了 哪些 事 


情 。 








ngx_process_events_and_timers 方 法 中 核心 的 操作 主要 有 以 下 3 个 : 


. 调用 所 使 用 的 事件 驱动 模块 实现 的 process_events 方 法 ， 处 理 网 络 
事件 。 


` 处 理 两 个 post 事 件 队 列 中 的 事件 ， 实 际 上 就 是 分 别 调用 
ngx_event_process_posted(cycle,&npgx_posted_accept_events) 和 
nox_event_process_posted(cycle,&negx_posted_events) 方 法 (参见 9.8.4 


了 ) 。 


. 处 理 定 时 器 事件 ， 实 际 上 就 是 调用 hex_event_expite_timets0 方 法 


(参见 9.7.3 节 ) 。 


后 两 项 操作 很 清晰 ， 而 调用 事件 驱动 模块 的 process_events 方 法 时 则 


需要 设置 两 个 关键 参数 timer 和 flags。Nginx 用 一 系列 宏 封装 了 
ngx_event_actions 接 口中 的 方法 ， 如 下 所 示 。 





#define 
#define 
#define 
#define 
#define 
#define 
#define 


ngx_process_changes 
ngx_process_events 
ngx_done_events 
ngx_add_event 
ngx_del event 
ngx_add_conn 
ngx_del_ conn 


ngx_event_actions. 
ngx_event_actions. 
ngx_event_actions. 
ngx_event_actions. 
ngx_event_actions. 
ngx_event_actions. 
ngx_event_actions. 


process_changes 
process_events 
done 

add 

del 

add_conn 
del_conn 


二 一 









[ 使 用 timer_resolution] 








1 Jimer 克 电 设置 
-1, flags 参数 设置 为 0 
[timer_resolution 未 使 用 ] = 


了 ngx_event_find_timer 


2) 执行 
得 到 最 近 超时 外 | 并 将 flags 设 置 为 NGX_UPDATE_TIME 
[检查 accept_mutex 锁 是 否 开 启 ] 










[accept_mutex 锁 打 开 ] 


[ngx_accept_disabled >0 





3 )ngx_accept_disabled 
鹿 值 ; 
[不 使 用 accept_mutex 锁 ][ngx_aceept_qisabikd <= 0 未 触发 负载 均衡 ] 全 


4 ) 贡 用 ngx_trylock_accept_ 
mutex 试图 获取 accept _mutex 锁 


[检查 是 否 获取 到 了 accept _mutex 锁 ] 
ngx_accept_mutex held 为 1 表示 持 有 本 accept_mutex 氏 i] 










[ngx_accept_mutex_held 为 0 表示 未 持 有 accept_mutex 锁 ] 







5) 将 flags 加 入 NGX_POST _ 


6) 将 timer 设 置 为 


ngx_accept_mutex_delay 





EVENTS 标 志 位 











7) 调 用 ngx_process _events 方 法 ， 
并 计算 出 耗 时 delta 


[ngx_ posted_accept_events 队列 中 有 事件 ] 


<》 





[ngx_posted_accept_events 队 列 为 空 | 8) 执 行 ee 一 events 





[ngx_accept_mutex_held 为 1 表示 持 有 了 锁 ] 
C2 \ 
ee 9 ) 调 用 ngx_shmtx_unlock 
[ngx_accept_mutex_held 为 0] 释放 accent_mutex 锁 





[ngx_process _events 方 法 耗 时 delta >0] 


一 一 \ 


10) 调用 ngx_event_expire_timers 


[delta=0] 执行 所 有 超时 事件 


< [ngx_posted_events 队 列 中 有 事件 ] 
1 执行 ngx_posted_events 


[ngx_posted_events 队列 为 空 ] 队列 中 的 事件 








大 


图 9-7 ngx_process_events_and_timets 方 法 中 的 事件 框架 处 理 流 程 


在 调用 ngx_process_events 时 ， 传 入 的 timer 和 flags 会 影响 时 间 精 度 以 
及 事件 是 人 否 会 在 post 队 列 中 处 理 。 下 面 简 要 分 析 一 下 图 9-7 中 的 11 个 步 
又 ， 其 中 前 6 个 步骤 都 与 参数 timer 和 flags 的 设置 有 天 。 


1) 如 果 配 置 文件 中 使 用 了 timer _ resolution 配置 项 ， 也 就 是 
ngx_timer resolution 值 大 于 0， 则 说 明 用 户 和 希望 服务 器 时 间 精 确 度 为 
ngx_timer_resolution 写 秒 。 这 时 ， 将 ngx_process_events 的 timer 参 数 设 
为 -1， 告 诉 ngx_process_events 方 法 在 检测 事件 时 不 要 等 待 ， 直 接 搜 集 所 
有 已 经 就 绪 的 事件 然后 返回 ， 同 时 将 flags 参 数 初 始 化 为 0， 它 是 在 告诉 
ngx_process_events 没 有 任何 附加 动作 。 





2) 如 果 没 有 使 用 timer_resolution， 那 么 将 调用 
ngx_event_find_timer() 方 法 (参见 表 9-5) 获取 最 近 一 个 将 要 触发 的 事件 
距离 现在 有 多 少 坚 秒 ， 然 后 把 这 个 值 赋予 timer 参 数 ， 告 诉 
ngx_process_events 方 法 在 检测 事件 时 如 果 没 有 任何 事件 ， 最 多 等 待 timer 
写 秒 就 返回 ; 将 flags 参 数 设置 为 NGX_UPDATE_TIME， 告 诉 
ngx_process_events 方 法 更 新 绥 存 的 时 间 (参见 9.6.3 市 中 
ngx_epoll_process_events 方 法 的 源 代码 ) 。 











3) 如 果 在 配置 文件 中 使 用 accept_mutex off 关 闭 accept_mutex 锁 ， 就 
直接 跳 到 第 7 步 ， 否 则 检测 负载 均衡 闷 值 变量 ngx_accept_disabled。 如 果 


ngx_accept_disabled 是 正 数 ， 则 将 其 值 减 去 1， 继 续 癌 下 执行 第 7 步 。 


4) 如 采 ngx_accept_disabled 是 负数 ， 表 明 还 没有 触发 到 负载 均衡 机 
制 〈 参 见 9.8.3 节 ) ， 此 时 要 调用 ngx_trylock_accept_mutex 方 法 试图 去 获 


取 accept_mutex 锁 (也 就 是 ngx_accept_mutex 变 量 表示 的 锁 )。 


5) 如 果 获 取 到 accept_mutex 锁 ， 也 就 是 说 ，ngx_accept_mutex_held 
标志 位 为 7， 那么 将 flags 参 数 加 上 NGX_POST_EVENTS 标 志 ， 告 诉 
ngx_process_events 方 法 搜集 到 的 事件 没有 直接 执行 它 的 handler 方 法 ， 而 
是 分 门 别 类 地 放 到 ngx_posted_accept_events 队 列 和 ngx_posted_events 队 
列 中 。timer 参 数 保持 不 变 。 


6) 如 果 没 有 获取 到 accept_mutex 锁 ， 则 意味 着 既 不 能 让 当前 worker 
进程 频繁 地 试图 抢 锁 ， 也 不 能 让 它 经 过 太 长 时 间 再 去 抢 锁 。 这 里 有 个 简 
单 的 判断 方法 ， 如 下 所 示 。 








if (timer == NGX_TIMER_INFINITE 
|| timer > ngx_accept_mutex_delay) 





timer = ngx_accept_mutex_delay; 








这 意味 着 ， 即 使 开启 了 timer_resolution 时 间 精 度 ， 也 需要 让 
ngX_process_events 方 法 在 没有 新 事件 的 时 候 至 少 等 待 
ngx_accept_mnutex_delay 室 秒 再 去 试图 抢 锁 。 而 没有 开局 时 间 精 度 时 ， 
如 果 最 近 一 个 定时 堪 事 件 的 超时 时 间距 离 现 在 超过 了 














ngx_accept_mnutex_delay 坚 秒 的 话 ， 也 要 把 timer 设 置 为 
ngx_accept_mnutex_delay 坚 秒 ， 这 是 因为 当前 进程 虽然 没有 抢 到 
accept_mnutex 锁 ， 但 也 不 能 让 ngx_process_events 方 法 在 没有 新 事件 的 时 
候 等 待 的 时 间 超 过 ngx_accept_mutex_delay 毫 秒 ， 这 会 影响 整个 负载 均 


衡 机 制 |。 





er 注意 ngx_accept_mutex_delay 变 量 与 npginx.conf 配 置 文件 中 的 


accept_mutex_delay 配 置 项 的 参数 相关 内 容 可 参见 9.5 节 。 


7) 调用 ngx_process_events 方 法 ， 并 计算 ngx_process_events 执 行 时 
消耗 的 时 间 ， 如 下 所 示 。 





delta = ngx_current_msec; 
(void) ngx_process_ events(cycle, timer, flags); 
delta = ngx_current msec - delta; 





其 中 ，delta 是 ngx_process_events 执 行 时 消耗 的 之 秒 数 ， 它 会 影响 第 
10 步 中 触发 定时 器 的 执行 。 


8) 如 果 ngx_posted_accept_events 队 列 不 为 空 ， 那 么 调用 
ngx_event_process_posted 方 法 执行 hgx_posted_accept_events 队 列 中 需要 
建立 新 连接 的 事件 。 


9) 如 果 ngx_accept_mutex_held 标 志 位 为 1， 则 表示 当前 进程 获得 了 
accept_mutex 锁 ， 而 且 在 第 8 步 中 也 已 经 处 理 完了 新 连接 事件 ， 这 时 需要 





调用 ngx_shmtx_unlock 释 放 accept_mnutex 锁 。 


10) 如 果 ngx_process_events 执 行 时 消耗 的 时 间 delta 大 于 0， 而 且 这 
时 可 能 有 新 的 定时 器 事件 被 触发 ， 那 么 需要 调用 ngx_event_expire_timers 
方法 处 理 所 有 满足 条 件 的 定时 器 事件 。 





11) 如 果 ngx_posted_events 队 列 不 为 室 ， 则 调用 
ngX_event_process_posted 方 法 执行 ngx_posted_events 队 列 中 的 普通 读 / 写 
事件 。 


至 此 ，ngx_process_events_and_timers 方 法 执行 完毕 。 注 意 ， 
ngx_process_events_and_timers 方 法 就 是 Nginx 实 际 上 人 处理 Web 服 务 的 方 
法 ， 所 有 业务 的 执行 都 是 由 它 开始 的 。ngx_process_events_and_timers 方 
法 涉及 Nginx 完 整 的 事件 驱动 机 制 ， 因 此 ， 它 也 把 之 前 介绍 的 内 容 整 合 
在 一 起 了 ， 读 者 需要 格外 注意 。 


9.9 文件 的 异步 IO 


本 章 之 前 提 到 的 事件 驱动 模块 都 是 在 处 理 网 络 事件 ， 而 没有 涉及 磁 
盘 上 文件 的 操作 。 本 节 将 讨论 Linux 内 核 2.6.2x 之 后 版 本 中 支持 的 文件 异 
步 1JO， 以 及 ngx_epoll_module 模 块 是 如 何 与 文件 异步 1/O 配 合 提供 服务 
的 。 这 里 提 到 的 文件 异步 WO 并 不 是 glibc 库 提供 的 文件 异步 WO。glibc 库 
提供 的 异步 WO 是 基于 多 线程 实现 的 ， 它 不 是 真正 意义 上 的 异步 WO。 而 
本 节 说 明 的 异步 JO 是 由 Linux 内 核实 现 ， 只 有 在 内 核 中 成 功 地 完成 了 磁 
盘 操 作 ， 内 核 才 会 通知 进程 ， 进 而 使 得 磁盘 文件 的 处 理 与 网 络 事件 的 处 
理 同样 高 效 。 











使 用 这 种 方式 的 前 提 是 Linux 内 核 版 本 中 必须 支持 文件 异步 WJO。 妆 
然 ， 它 带 来 的 好 处 也 非常 明显 ，Nginx 把 读 取 文件 的 操作 异步 地 提交 给 
内 核 后 ， 内 核 会 通知 MO 设备 独立 地 执行 操作 ， 这 样 ，Nginx 进 程 可 以 继 
续 充 分 地 占用 CPU。 而 且 ， 当 大 量 读 事件 堆积 到 LO 设备 的 队列 中 时 ， 
将 会 发 挥 出 内 核 中 “电梯 算法 ”的 优势 ， 从 而 降低 随机 读 取 磁盘 书 区 的 成 
本 。 


人 @@ 注意 Linux 内 核 级 别 的 文件 异步 I/O 是 不 支持 缓存 操作 的 ， 也 
就 是 说 ， 即 使 需要 操作 的 文件 块 在 Linux 文 件 缓存 中 存在 ， 也 不 会 通过 
读 取 、 更 改 缓存 中 的 文件 块 来 代替 实际 对 磁盘 的 操作 ， 虽 然 从 阻塞 


wotket 进 程 的 角度 上 来 说 有 了 很 大 好 转 ， 但 是 对 单个 请 求 来 说 ， 还 是 有 
可 能 降低 实际 处 理 的 速度 ， 因 为 原先 可 以 从 内 存 中 快速 获取 的 文件 块 在 
使 用 了 异步 1/O 〇 后 则 一 定 会 从 磁盘 上 读 取 。 异 步 文件 1/O 〇 是 把 “ 双 丸 
剑 ”， 关 键 要 看 使 用 场景 ， 如 果 大 部 分 用 户 请 求 对 文件 的 操作 都 会 落 到 
文件 缓存 中 ， 那 么 不 要 使 用 异步 1/ 〇 ， 反 之 则 可 以 试 着 使 用 文件 异步 
LI/O， 看 一 下 是 否 会 为 服务 带 来 并 发 能 力 上 的 提升 。 


目前 ，Nginx 仅 支持 在 读 取 文 件 时 使 用 异步 I/O ， 因 为 正常 写 入 文件 
往往 是 写 入 内 存 中 就 立刻 返回 ， 效 率 很 高 ， 而 使 用 异步 IJ/O 写 入 时 速 


9.9.1 _ Linux 内核 提 供 的 文件 异步 IO 


Linux 内 核 提 供 了 5 个 系统 调用 完成 文件 操作 的 异步 W/O 功 能 ， 见 表 9- 


表 9-7 Linux 内核 提供 的 文件 异步 I/O 操 作 方 法 


二 EX 
初始 化 文件 异步 VO 的 上 下 文 ， 
nr_events 表示 需要 初始 化 的 异步 了 | 执行 成 功 后 ctxp 就 是 分 配 的 上 下 
O 上 下 文 可 以 处 理 的 事件 的 最 小 个 数 , | 文 描述 符 ， 这 个 异步 IO 上下文 
ctxp 是 文件 异步 IO 的 上 下 文 描述 符 指 针 | 将 至 少 可 以 处 理 mnr_events 个 事 
件 。 返回 0 表示 成 功 
销毁 文件 异步 VO 的 上 下 文 
返回 0 表示 成 功 


int 10_setup(unsigned nr _events. 


alo_context t *ctxp) 


int io_destroy (aio_context t ctx) ctx 是 文件 异步 IO 的 上 下 文 描述 符 


ctx 是 文件 异步 IO 的 上 下 文 描述 符 ， 
nr 是 一 次 提交 的 事件 个 数 ，cbp 是 需要 
提交 的 事件 数组 中 的 首 个 元 素 地 址 

ctx 是 文件 异步 VO 的 上 下 文 描 述 符 ,| 取消 之 前 使 用 io_sumbit 提交 
iocb 是 要 取消 的 异步 IO 操作 ， 而 result | 的 一 个 文件 异步 IO 操作。 返回 
表示 这 个 操作 的 执行 结果 0 表示 成 功 

ctx 是 文件 异步 Jo 的 上 下 文 描述 符 ; 


int io_submit(aio_context t ctx, 是 交 文 件 异 步 IO 操作。 返回 


long ni, struct iocb *cbp[]) 值 表 示 成 功 提交 的 事件 个 数 
int io_cancel(aio context t ctx, struct 


iocb *iocb, struct io_event *result) 


min nr 表示 至 少 要 获取 min nr 个 事件 ; 


int io_getevents(aio context t ctx, . parle mre ” ee 
而 nr 表示 至 多 获取 nr 个 事件 ， 它 与 


events 数组 的 个 数 一 般 是 相同 的 ; events 
是 执行 完成 的 事件 数组 ; timeout 是 超时 
时 间 ， 也 就 是 在 获取 min_nr 个 事件 前 的 
等 待 时 间 


long min_nr, long nr. 从 已 经 完成 的 文件 异步 IO 操 


作 队 列 中 读 取 操作 


struct 10_event *events, struct 


timespec *timeout) 





表 9-7 中 列举 的 这 5 种 方法 提供 了 内 核 级 别 的 文件 异步 WO 机 制 ， 使 用 

前 需要 先 调用 io_setup 方 法 初始 化 异步 WO 上 下 文 。 虽 然 一 个 进程 可 以 拥 
有 多 个 寞 步 WO 上 下 文 ， 但 通常 有 一 个 束 足 够 了 。 调 用 io_setup 方 法 后 会 
获得 这 个 异步 JO 上下文 的 描述 符 (aio_context_t 类 型 ， 这 个 描述 符 和 
epoll_create 返 回 的 描述 符 一 样 ， 是 贯 罕 始终 的 。 注 意 ，nr_events 只 是 指 
定 了 异步 WO 人 至少 初始 化 的 上 下 文 容量 ， 它 并 没有 限制 最 大 可 以 处 理 的 
异步 WO 事件 数目 。 为 了 便于 理解 ， 不 妨 将 io_setup 与 epoll_create 进 行 对 
比 ， 它 们 还 是 很 相似 的 。 








既然 把 epol 和 异步 JO 进 行 对 比 ， 那 么 哪些 调用 相当 于 epoll_ctl 呢 ? 


就 是 io_submit 和 io_cancel。 其 中 io_submit 相 当 于 向 异步 JO 中 添加 事件 ， 
而 io_cancel 则 相当 于 从 异步 IO 中 移 除 事件 。io_submit 中 用 到 了 一 个 结构 
体 iocb， 下 面 简单 地 看 一 下 它 的 定义 。 





Struct iocb { 
/* 存 储 着 业务 需要 的 指针 。 例 如 ， 在 


Nginx 中 ， 这 个 字段 通常 存储 着 对 应 的 


ngx_event 七 事 件 的 指针 。 它 实际 上 与 





II0_getevents 方 法 中 返回 的 


io_event 结 构 体 的 


data 成 员 是 完全 一 致 的 


*/ 
U_int64 t aio_data; 
// 不 需要 设置 


U_int32 _t PADDED(aio_ key, aio_reserved1); 
// 操作 码 ， 其 取 值 范围 是 


IO_iocb_cmd t 中 的 枚 举 命 令 


U_int16 t aio_ lio opcode; 
// 请 求 的 优先 级 





int16_t aio_reqprio; 
// 文件 描述 符 


U_int32_t aio_fildes 
// 读 


/ 写 操作 对 应 的 用 户 态 缓冲 区 


U_int64 t aio_buf; 
// 读 


/ 写 操作 的 字 节 长 度 


U_int64 _t aio_nbytes 
// 读 


/ 写 操作 对 应 于 文件 中 的 偏 移 量 


int64_t alio_offset 
// 保留 字段 


U_int64 t aio_reserved2; 
/* 表 示 可 以 设置 为 


IOCB_FLAG_RESFD， 它 会 告诉 内 核 当 有 异步 


I/0 请 求 处 理 完成 时 使 用 


eventfd 进 行 通知 ， 可 与 


epol11 配 合 使 用 ， 其 在 


Nginx 中 的 使 用 方法 可 参见 


9.9.2 节 


2 
U_int32_t aio_flags， 
// 表示 当 使 用 


IOCB_FLAG_RESFD 标 志 位 时 ， 用 于 进行 事件 通知 的 句柄 


U_int32_ t aio_resfd ， 


> 





因此 ， 在 设置 好 iocb 结 构 体 后 ， 束 可 以 辣 寞 步 WO 提 交 事 件 了 。 


aio_lio_opcode 操 作 码 指定 了 这 个 事件 的 操作 类 型 ， 它 的 取 值 范围 如 下 。 





typedef enum io_iocb cmd { 
// 异步 读 操作 


IO_CMD_PREAD = 9， 
// 异步 写 操 作 


IO_CMD_PWRITE = 1, 
// 强制 同步 


I0_CMD_FSYNC = 2, 
// 目前 未 使 用 


IO_CMD_FDSYNC = 3, 
// 目前 未 使 用 


IO_CMD_POLL = 5, 
// 不 做 任何 事情 


IO_CMD_NOOP = 6, 
} io_iocb_cmd _t; 








在 Nginx 中 ， 仅 使 用 了 IO_CMD_PREAD 命 令 ， 这 是 因为 目前 仅 支持 
文件 的 异步 JO 读 取 ， 不 支持 异步 JO 的 写 入 。 这 其 中 一 个 重要 的 原因 是 
文件 的 异步 VO 无 法 利用 缓存 ， 而 写 文件 操作 通常 是 落 到 缓存 中 的 ， 
Linux 存 在 统一 将 缓存 中 “ 脏 ? 数 据 刷新 到 磁盘 的 机 制 。 





这 样 ， 使 用 io_submit 回 内 核 提 交 了 文件 异步 JO 操 作 的 事件 后 ， 再 
使 用 io_cancel 则 可 以 将 已 经 提交 的 事件 取消 。 


如 何 获 取 已 经 完成 的 异步 JO 事 件 呢 ? io_getevents 方 法 可 以 做 到 ， 
它 相 当 于 epoll 中 的 epoll_wait 方 法 。 这 里 用 到 了 io_event 结 构 体 ， 下 面 看 
一 下 它 的 定义 。 





struct io_event { 
// 与 提交 事件 时 对 应 的 


iocb 结 构 体 中 的 


aio_data 是 一 致 的 


uint64 t data; 
// 指向 提交 事件 时 对 应 的 





1ocb 结 构 体 


uint64 t obj; 
// 异步 


I/0 请 求 的 结构 。 


res 大 于 或 等 于 


0 时 表示 成 功 ， 小 于 


9 时 表示 失败 


int64_t res; 
// 保留 字段 


int64_t res2; 





这 样 ， 根 据 获取 的 io_event 结 构 体 数组 ， 就 可 以 获得 已 经 完成 的 异 


步 IO 操 作 了 ， 特 别 是 iocb 结 构 体 中 的 aio_data 成 员 和 io_event 中 的 data， 
可 用 于 传递 指针 ， 也 束 是 说 ， 业 务 中 的 数据 结构 、 事 件 完 成 后 的 回调 方 
法 都 在 这 里 。 


进程 退出 时 需要 调用 io_destroy 方 法 销毁 异步 JO 上 下 文 ， 这 相当 于 
调用 close 关 闭 epoll 的 描述 符 。 


Linux 内 核 提 供 的 文件 异步 VO 机 制 用 法 非常 简单 ， 它 充分 利用 了 在 
内 核 中 CPU 与 VO 设备 是 各 自 独 立 工 作 的 这 一 特性 ， 在 提交 了 异步 1/O 操 
作 后 ， 进 程 完全 可 以 做 其 他 工作 ， 直 到 空闲 再 来 查看 异步 IO 操 作 是 否 


完成 。 
9.9.2 ngx_epoll module 模 块 中 实现 的 针对 文件 的 异步 IO 


在 Nginx 中 ， 文 件 异 步 /O 事 件 完成 后 的 通知 是 集成 到 epoll 中 的 ， 它 
是 通过 9.9.1 节 中 介绍 的 OCB_FLAG_RESFD 标 志 位 完成 的 。 下 面 看 看 文 
件 异 步 WO 事 件 在 ngx_epoll_module 模 块 中 是 如 何 实 现 的 ， 其 中 在 文件 异 
步 WO 机 制 中 定义 的 全 局 变量 如 下 。 


// 用 于 通知 异步 





I/0 事 件 的 描述 符 ， 它 与 


iocb 结 构 体 中 的 


aio_resfd 成 员 是 一 致 的 


int ngx_eventfd = -1; 


// 异步 


I/0 的 上 下 文 ， 全 局 唯一 ， 必 须 经 过 


io_setup 初 始 化 才能 使 用 


aio_context_t ngx_aio ctx = 0; 
/异步 


IT/0 事 件 完成 后 进行 通知 的 描述 符 ， 也 就 是 


ngx_eventfd 所 对 应 的 





ngx_event 七 事件 


*/ 
static ngx_event_t ngx_eventfd event; 
/异步 


I/0 事 件 完 成 后 进行 通知 的 描述 符 


ngx_eventfd 所 对 应 的 


ngx_connection_t 连 接 


*/ 
static ngx_connection t ngx_eventfd_conn; 





在 9.6.3 节 的 ngx_epoll_init 代 码 中 ， 在 epoll_create 执 行 完 成 后 如 果 开 
启 了 文件 异步 /OO 功能， 则 会 调用 ngx_epoll_aio_init 方 法 。 现 在 详细 描述 
一 下 ngx_epoll_aio_init 方 法 中 做 了 些 什 么 ， 如 下 所 示 。 





#define SYS_eventfd 323 
static void ngx_epoll aio init(ngx_cycle t *cycle, ngx_ epoll conf_t *epcf) 
{ 

int n; 

struct epoll event ee,; 

// 使 用 


Linux 中 第 


323 个 系统 调用 获取 一 个 描述 符 句 本 


ngx_eventfd = syscall(SYS eventfd, 0); 


// 设置 


ngx_eventfd 为 无 阻塞 


If (ioctl(ngx_eventfd, FIONBIO, &n) == -1) { 


} 
// 初始 化 文件 异步 


I/0 的 上 下 广 


if (io_setup(epcf->aio_requests, &ngx_aio ctx) == -1) { 


po 于 异步 
I/0 完 成 通知 的 
ngx_eventfd_event 事 件 ， 它 与 
ngx_eventfd_conn 连 接 是 对 应 的 


4 
ngx_eventfd_event ,data = &ngx_eventfd_conn,; 


// 在 异步 
I/0 事 件 完 成 后 ， 使 用 


ngx_epoll_eventfd_handler 方 法 处 理 


ngx_eventfd_event.handler = ngx_epoll_eventfd_handJer ; 
ngx_eventfd_event ,1og = Cycle->1odg ; 

ngx_eventfd_event ,active = 1; 

// 初始 化 


ngx_eventfd_conn 连 接 


ngx_eventfd_conn.fd = ngx_eventfd; 
// ngx_eventfd_conn 连 接 的 读 事件 就 是 上 面 的 


ngx_eventfd_event 
ngx_eventfd_conn.read = &ngx_eventfd_event ; 
ngx_eventfd_conn,1og = Cycle->1og ; 
ee.events = EPOLLIN|EPOLLET 
ee.data.ptr = &ngx_eventfd_conn; 
// 向 


epoll 中 添加 到 异步 
I/0 的 通知 描述 符 


ngx_eventfd 
if (epoll ctil(ep, EPOLL _ CTL _ ADD, ngx_eventfd, &ee) != -1) { 
return; 
} 





这 样 ，ngx_epoll_aio_init 方 法 会 把 异步 /0 与 epoll 结 合 起 来 ， 当 某 一 
个 异步 IO 事件 完成 后 ，ngx_eventfd 句 柄 就 处 于 可 用 状态 ， 这 样 
epoll_wait 在 返回 ngx_eventfd_event 事 件 后 就 会 调用 它 的 回调 方法 
ngx_epoll_eventfd_handler 处 理 已 经 完成 的 异步 WO 事件 ， 下 面 看 一 下 
ngx_epoll_eventfd_handler 方 法 主要 在 做 些 什 么 ， 代 码 如 下 所 示 。 





static void ngx_epoll eventfd handler(ngx_event_t *ev) 


{ 


int n, events; 
uint64 t ready; 
ngx_event_t *e; 
// 一 次 性 最 多 处 理 


64 个 事件 


Struct io_event event[64]; 
struct timespec ts; 
/* 获 取 已 经 完成 的 事件 数目 ， 并 设置 到 


ready 中 ， 注 意 ， 这 个 
ready 是 可 以 大 于 
64 的 


7 
n = read(ngx_eventfd, &ready, 8); 





// ready 表 示 还 未 处 理 的 事件 。 当 


ready 大 于 


9 时 继续 处 理 


while (ready) { 
// 调用 


io_getevents 获 取 已 经 完成 的 异步 


I/0 事 件 


events = io_getevents(ngx_aio ctx, 1, 64, event, &ts); 
if (events > 0) { 
// 将 


ready 减 去 已 经 取出 的 事件 


ready -= events,; 


// 处 理 


event 数 组 里 的 事件 


for (i = 0; i < events,; i++) { 
// data 成 员 指 向 这 个 异步 








I/0 事 件 对 应 着 的 实际 事件 


e = (ngx_event t *) (uintptr_t) event[i].data; 


// 将 该 事件 放 到 





ngx_posted_events 队 列 中 延 后 执行 


ngx_post_event(e, &ngx_posted events); 
continue; 


} 
if (events == 0) { 
return; 


return; 





整个 网 络 事件 的 张 动 机 制 束 是 这 样 通过 ngx_eventfd 通 知 描述 符 和 
ngx_epoll_eventfd_handler 回 调 方法 ， 并 与 文件 异步 JO 事 件 结合 起 来 
的 。 


那么 ， 怎 样 向 异步 JO 上 下 文中 提交 异步 JO 操 作 呢 ? 看 看 
ngx_linux_aio_read.c 文 件 中 的 ngx_file_aio_read 方 法 ， 在 打开 文件 异步 
W/O 后 ， 这 个 方法 将 会 负责 磁盘 文件 的 读 取 ， 如 下 所 示 。 





ssize_t ngx_file aio _ read(ngx_file t *file, u_char *buf, size_t size, off_t offset, 





ngx_err 
struct iocb 
ngx_event_t 
ngx_event_aio_t 


aio = file->aio 
ev = &aio->even 


err; 
*piocb[1]; 
*evVv; 


[A 


t; 


ngx_memzero(&aio->aiocb, sizeof(struct iocb)); 


/* 设 置 


9.9.1 节 中 介绍 过 的 


iocb 结 构 体 ， 这 里 的 


aiocb 成 员 就 是 


iocb 类 型 。 注 意 ， 


aio_data 已 经 设置 为 这 个 


ngx_event_t3 





件 的 指针 ， 这 样 ， 从 


io_getevents 方 法 获取 的 


IIo_event 对 象 中 的 


data 也 是 这 个 指针 


aio->aiocb.aio_ 
aio->aiocb.aio . 
aio->aiocb.aio 
aio->aiocb.aio_ 
aio->aiocb.aio_ 
aio->aiocb.aio_ 
aio->aiocb.aio 
aio->aiocb.aio_ 


data = (uint64 t) (uintptr_t) ev; 
1io opcode = IOCB_CMD_PREAD ; 
fildes = file->fd， 

buf = (uint64 t) (uintptr_t) buf， 
nbytes = size,; 

offset = offset,; 

flags IOCB_FLAG_RESFD ， 

resfd ngx_eventfd ; 


/* 设 置 事件 的 回调 方法 为 


ngx_file_aio_event_handler， 它 的 调用 关系 类 似 这 样 





:epoll_wait 中 调用 





ngx_epoll_eventfd_handler 方法 将 当前 事件 放 入 到 


ngx_posted_events 队 列 中 ， 在 延 后 执行 的 队列 中 调用 


ngx_file_aio_event_handler 方 法 





*/ 
ev->handler = ngx_file aio event_handler; 
piocb[0] = &aio->aiocb,; 
/* 调 用 





IO_Submajt 向 


ngx_aio_ctx 异 步 


I/0 上 下 文中 添加 





1 个 事件 ， 返 回 


1 表示 成 功 


*/ 
If (io_submit(ngx_aio_ctx, 1, piocb) == 1) { 
ev->active = 1; 
ev->ready = 0; 
ev->complete = 0; 
return NGX_AGAIN ; 





下 面 看 一 下 ngx_event_aio_t 结 构 体 的 定义 。 





typedef struct ngx_event aio _s ngx_event_aio_t; 
struct ngx_event aio s { 

void *data; 

// 这 是 真正 由 业务 模块 实现 的 方法 ， 在 异步 


I/0 事 件 完成 后 被 调用 


ngx_event_handler_pt handler 
ngx_file_t *file， 
ngx_fd_t fd; 
#if (NGX_HAVE_EVENTFD) 
Int64 t res; 
#else 
ngx_err_t err,; 
size_t nbytes,; 
#endif 
#if (NGX_HAVE_AIO_SENDFILE) 
off_t last_offset,; 
#endif 
// 这 里 的 


ngx_aiocb_t 就 是 


ijocb 结 构 体 


ngx_aiocbh_t aiocb; 
ngx_event_t event,; 


}; 





这 样 ，ngx_file_aio_read 方 法 会 同 寞 步 WO 上 下 文中 添 加 事件 ， 该 
epoll_wait 在 通过 ngx_eventfd 摘 述 符 检 测 到 异步 WO 事件 后 ， 会 再 调用 
ngx_epoll_eventfd_handler 方 法 将 io_event 事 件 取出 来 ， 放 入 
ngx_posted_events 队 列 中 延 后 执行 。ngx_posted_events 队 列 中 的 事件 执 
行 时 ， 则 会 调用 ngx_file_aio_event_handler 方 法 。 下 面 看 一 下 
ngx_file_aio_event_handler 方 法 做 了 些 什么 ， 代 码 如 下 所 示 。 





static void ngx_file aio event_ handler(ngx_event_t *ev) 





{ 
ngx_event_ aio t *aio,; 
aio = ev->data; 
aio->handler (ev); 

} 
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这 里 调用 了 ngx_event_aio_t 结 构 体 的 handler 回 调 方 法 ， 这 个 回调 方 
法 是 由 真正 的 业务 模块 实现 的 ， 也 就 是 说 ， 任 一 个 业务 模块 想 使 用 文件 
异步 JO， 就 可 以 实现 handler 方 法 ， 这 样 ， 在 文件 异步 操作 完成 后 ， 该 
方法 就 会 被 回调 。 


9.10 ITCP 协 议 与 Nginx 


作为 Web 服 务 器 的 nginx， 主 要 任务 当然 是 处 理 好 基于 TCP 的 HTTP 
协议 ， 本 节 将 深入 TCP 协 议 的 实现 细节 (Qinux 下 〉 以 更 好 地 理解 Nginx 
事件 处 理 机 制 。 


TCP 是 一 个 面向 连接 的 协议 ， 它 必须 基于 建立 好 的 TCP 连 接 来 为 通 
信 的 两 方 提供 可 靠 的 字 市 流 服 务 。 建 六 TCP 连 接 是 我 们 耳熟能详 的 三 次 
握手 : 


1) 客户 端 问 服务 器 发 起 连接 (SYN) 。 
2) 服务 器 确认 收 到 并 同 客 户 端 也 发 起 连接 (ACK+SYN) 。 
3) 客户 端 确认 收 到 服务 器 发 起 的 连接 (ACK) 。 


这 个 建立 连接 的 过 程 是 在 操作 系统 内 核 中 完成 的 ， 而 如 Nginx 这 样 
的 应 用 程序 只 是 从 内 核 中 取出 已 经 建立 好 的 TCP 连 接 。 大 多 时 候 ， 
Nginx 是 作为 连接 的 服务 器 方 存在 的 ， 我 们 看 一 看 Linux 内 核 是 怎样 处 理 
TCP 连 接 建 立 的 ， 如 图 9-8 所 示 。 







1.2 插 入 队列 


2 由 队列 中 取出 







.3 插入 队列 





3 调用 accept 取 出 连接 套 接 字 






尘 室 时 THONP 


图 9-8 服务 器 端 建立 TCP 连 接 的 简化 示意 图 


图 9-8 中 简单 地 表达 了 一 个 观点 : 内 核 在 我 们 调用 1listen 方 法 时 ， 就 
已 经 为 这 个 监听 端口 建立 了 SYN 队 列 和 ACCEPT 队 列 ， 当 客户 端 使 用 
connect 方 法 向 服务 器 发 起 TCP 连 接 ， 随 后 图 中 1.1 步 又 客户 端的 SYN 包 到 
达 了 服务 器 后 ， 内 核 会 把 这 一 信息 放 到 SYN 队 列 ( 即 未 完成 握手 队列 ) 
中 ， 同 时 回 一 个 SYN+ACK 包 给 客户 端 。2.1 步 又 中 客户 端 再 次 发 来 了 针 
对 服务 器 SYN 包 的 ACK 网 络 分 组 时 ， 内 核 会 把 连接 从 SYN 队 列 中 取出 ， 
再 把 这 个 连接 放 到 ACCEPT 队 列 〈 即 已 完成 握手 队列 〉 中。 而 服务 器 在 


第 3 步调 用 accept 方 法 建立 连接 时 ， 其 实 就 是 直接 从 ACCEPT 队 列 中 取出 
己 经 建 好 的 连接 而 已 。 


这 样 ， 如 果 大 量 连 接 同时 到 来 ， 而 应 用 程序 不 能 及 时 地 调用 accept 
方法 ， 就 会 导致 以 上 两 个 队列 满 CACCEPT 队 列 满 ， 进 而 也 会 导致 SYN 
队列 满 ) ， 从 而 导致 连接 无 法 建立 。 这 其 实 很 常见 ， 比 如 Nginx 的 每 个 
worker 进 程 都 负责 调用 accept 方 法 ， 如 果 一 个 Nginx 模 块 在 处 理 请 求 时 长 
时 间 陷 入 了 某 个 方法 的 执行 中 (如 执行 计算 或 者 等 等 IO，， 就 有 可 能 
致 新 连接 无 法 建立 。 





建立 好 连接 后 ，TCP 提 供 了 可 靠 的 字 贡 流 服 务 。 怎 么 理解 所 谓 
的 “可 靠 ” 呢 ?可 以 简单 概括 为 以 下 4 反 : 





1) TCP 的 send 方 法 可 以 发 送 任 音 大 的 长 上 度 ， 但 数据 链 路 层 不 会 允许 
一 个 报 文 太 大 的 ， 当 报 文 长 度 超过 MTU 大 小 时 ， 它 一 定 会 把 超大 的 报 
文 切 成 小 报 文 。 这 样 的 场景 是 不 被 TCP 接 受 的 ， 切 分 报 文 段 既 然 不 可 避 
免 ， 那 么 就 只 能 发 生 在 TCP 协 议 内 部 ， 这 才 有 是 最 有 效率 的 。 








) 每 一 个 报 文 在 发 出 后 都 必须 收 到 “回执 ”一 一 ACK， 确 保 对 方 收 
到 ， 和 否则 会 在 超时 时 间 达 到 后 重 发 。 相 对 的 ， 接 收 到 一 个 报 文 时 也 必须 
发 送 一 个 ACK 告 诉 对 方 。 





3) 报 文 在 网 络 中 传输 时 会 失 序 ，TCP 接 收 端 需要 重新 排序 失 序 的 
报 文 ， 组 合成 发 送 时 的 原 序 再 给 到 应 用 程序 。 当 然 ， 重 复 的 报 文 也 要 丢 





六 


4) 当 连 接 的 两 端 处 理 速 度 不 一 致 时， 为 防止 TCP 绥 冲 区 溢出 ， 
要 有 个 流量 控制 ， 减 组 速度 更 快 一 方 的 发 送 速度 。 


从 以 上 4 点 可 以 看 到 ， 内 核 为 每 一 个 TCP 连 接 都 分 配 了 内 存 分 别 充 
当 发 送 、 接 收 缓冲 区 ， 这 与 Nginx 这 种 应 用 程序 中 的 用 户 态 缓存 不 同 。 
搞 清 楚 内 核 的 TCP 读 写 缓存 区 ， 对 于 我 们 判断 Nginx 的 处 理 能 力 很 有 玫 
助 ， 毕 竟 无 论 内 核 还 是 应 用 程序 都 在 抢 物 理 内 存 。 


先 来 看 看 调用 send 这 样 的 方法 发 送 TCP 字 市 流 时 ， 内 核 到 底 做 了 哪 
些 事 。 图 9-9 是 一 个 简单 的 send 方 法 调用 时 的 流程 示意 图 。 





TCP 连 接 建 立时 ， 就 可 以 判断 出 双方 的 网 络 间 最 适宜 的 、 不 会 被 再 
次 切 分 的 报 文大 小 ，TCP 层 把 它 叫 做 MSS 最 大 报 文 段 长 度 〈 当 然 ，MSS 
是 可 变 的 ) 。 在 图 9-9 的 场景 中 ， 假 定 待 发 送 的 内 存 将 按照 MSS 被 切 分 
为 3 个 报 文 ， 应 用 程序 在 第 1 步调 用 send 方 法 、 第 10 步 send 方 法 返回 之 
间 ， 内 核 的 主要 任务 是 把 用 户 态 的 内 存 内 容 拷贝 到 内 核 态 的 TCP 绥 冲 区 
上 ， 在 第 5 步 时 假定 内 核 缓存 区 暂时 不 足 ， 在 超时 时 间 内 又 等 到 了 足够 
的 空闲 空间 。 从 图 中 可 以 看 到 ，send 方 法 成 功 返 回 并 不 等 于 就 把 报 文 发 
送出 去 了 《当然 更 不 等 于 对 方 接收 到 了 报 文 ) 。 
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图 9-9 ”send 方 法 执行 时 的 流程 示意 图 





当 调 用 recv 这 样 的 方法 接收 报 文 时 ，Nginx 是 基于 事件 驱动 的 ， 也 
就 是 说 只 有 epoll 通 知 worker 进 程 收 到 了 网 络 报 文 ，recv 才 会 被 调用 
(socket 也 被 设 为 非 阻塞 模式 ) 。 图 9-10 就 是 一 个 这 样 的 场景 ， 在 第 1~4 
步 表 示 接 收 到 了 无 序 的 报 文 后 ， 内 核 是 怎样 重新 排序 的 。 第 5 步 开始 ， 
应 用 程序 调用 了 recv 方 法 ， 内 核 开 始 把 TCP 读 缓冲 区 的 内 容 拷贝 到 应 用 





程序 的 用 户 态 内 存 中 ， 第 13 步 recv 方 法 返回 拷贝 的 字 节 数 。 图 中 用 到 了 
linux 内 核 中 为 TCP 准 备 的 2 个 队列 : receive 队 列 是 允许 用 户 进程 直接 读 
取 的 ， 它 是 将 已 经 接收 到 的 TCP 报 文 ， 去 除了 TCP 头 部 、 排 好 序 放 入 
的 、 用 户 进 程 可 以 直接 按 序 读 取 的 队列 ;out_of_order 队 列 存放 乱 序 的 
报 文 。 











回 过 头 来 看 ，Nginx 使 用 好 TCP 协 议 主要 在 于 如 何 有 效率 地 使 用 
CPU 和 内 存 。 只 在 必要 时 才 调 用 TCP 的 send/recv 方 法 ， 这 样 就 避免 了 无 
谓 的 CPU 浪费 。 例 如 ， 只 有 接收 到 报 文 ， 甚 至 只 有 接收 到 足够 多 的 报 文 
(SO_RCVLOWAT 阔 值 ) ，worker 进 程 才 有 可 能 调用 recv 方 法 。 同 样 ， 
只 在 发 送 缓冲 区 有 空闲 空间 时 才 去 调用 send 方 法 。 这 样 的 调用 才 是 有 效 
率 的 。Nginx 对 内 存 的 分 配 是 很 节俭 的 ， 但 Linux 内 核 使 用 的 内 存 又 如 何 
控制 呢 ? 
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12 ) 已 经 拷贝 的 字 节 数 超过 最 低 接 收 阅 值 ， 
而 且 backlog 队 列 为 空 











图 9-10 ”recv 方 法 执行 时 的 流程 示意 图 


首先 ， 我 们 可 以 控制 内 存 缓存 的 上 限 ， 例 如 基于 setsockopt 方 法 实 
现 的 SO_SNDBUF、SO_RCVBUF (Nginx 的 listen 配 置 里 的 sndbuf 和 
rcvbuf 也 是 在 改 它 们 ， 参 见 2.4.1 节 ) 。SO_SNDBUF 表 示 这 个 连接 上 的 
内 核 写 缓存 上 限 〈 事 实 上 SO_SNDBUF 也 并 不 是 精确 的 上 限 ， 在 内 核 中 
会 把 这 个 值 翻 一 倍 再 作为 写 缓存 上 限 使 用 ) 。 它 受制 于 系统 级 配置 的 上 
下 限 net.core.wmem_max 〈 人 参见 1.3.4 节 ) 。SO_RCVBUF 同 理 。 读 写 缓存 
的 实际 内 存 大 小 与 场景 有 关 。 对 读 缓存 来 说 ， 接 收 到 一 个 来 自 连 接 对 端 








的 TCP 报 文 时 ， 会 导致 该 缓存 增加 ， 如 果 超 过 了 读 缓存 上 限 ， 那 么 这 个 
报 文 会 被 丢弃 。 当 进程 调用 read、recv 这 样 的 方法 读 取 字 节 流 时 ， 读 组 
存 就 会 减少 。 因 此 ， 读 缓存 是 一 个 动态 变化 的 、 实 际 用 到 多 少 才 分 配 多 
少 的 缓冲 内 存 。 当 用 户 进程 调用 send 方 法 发 送 TCP 字 节 流 时 ， 就 会 造成 
写 缓存 增 大 。 当 然 ， 如 果 写 缓存 已 经 到 达 上 限 ， 那 么 号 缓存 维持 不 变 ， 
占用 户 进 程 返 回 失败 。 而 每 当 接 收 到 连接 对 端 发 来 的 ACK， 确 认 了 报 文 
的 成 功 发 送 时 ， 写 缓存 就 会 减少 。 可 见 缓存 上 限 所 起 作用 为 : 丢弃 新 报 
文 ， 防 止 这 个 TCP 连 接 消耗 太 多 的 内 存 。 





其 次 ， 我 们 可 以 使 用 Linux 提 供 的 自动 内 存 调整 功能 。 





net.ipv4.tcp_ moderate_rcvbuf = 1 





默认 tcp_moderate_rcvbuf 配 置 为 7， 表示 打开 了 了 TCP 内存 自动 调整 功 
能 。 知 配置 为 0， 这 个 功能 将 不 会 生效 〈 慎 用 ) 。 

人 @@ i 意 。 当 我 们 在 编程 中 对 连接 设置 了 SO_SNDBUF、 
SO_RCVBUF， 将 会 使 Linux 内 核 不 再 对 这 样 的 连接 执行 自动 调整 功能 ! 


那么 ， 这 个 功能 到 底 是 怎样 起 作用 的 呢 ? 举 个 例子 ， 请 看 下 面 的 绥 
存 上 限 配置 : 





net.ipv4.tcp_rmem = 8192 87380 16777216 
net.ipv4.tcp wmem = 8192 65536 16777216 
net.ipv4.tcp _ mem = 8388608 12582912 16777216 





tcp_rmem[3] 数 组 表示 任何 一 个 TICP 连 接 上 的 读 缓存 上 限 ， 其 中 
tcp_rmem[0] 表 示 最 小 上 限 ，tcp_rmem[1] 表 示 初 始 上 限 “〈 注 意 ， 它 会 履 
兰 适 用 于 所 有 协议 的 rmem_default 配 置 ) ，tcp_rmem[2] 表 示 最 大 上 限 。 


tcp_wmem[3] 数 组 表示 写 缓存 ， 与 tcp_rmem[3] 类 似 。 


tcp_mem[3] 数 组 就 用 来 设 定 TCP 内 存 的 整体 使 用 状况 ， 所 以 它 的 值 
很 大 《〈 它 的 单位 也 不 是 字 节 ， 而 是 页 一 一 4KB 或 者 8KB 等 这 样 的 单 
位 ! ) 。 这 3 个 值 定义 了 TCP 整 体内 存 的 无 压力 值 、 压 力 模 式 开 启 冰 
值 、 最 大 使 用 值 。 以 这 3 个 值 为 标记 点 则 内 存 共 有 4 种 情况 (如 图 9-11 所 


不 ) : 


1) 当 TCP 整 体内 存 小 于 tcp_mem[0] 时 ， 表 示 系 统 内 存 总 体 无 压 
力 。 大 之 前 内 存 曾 经 超过 了 tcp_mem[1] 使 系统 进入 和 内存 压 力 模式 ， 那 么 
此 时 也 会 把 压力 模式 关闭 。 此 时 ， 只 要 TCP 连 接 使 用 的 缓存 没有 达到 上 
限 ， 那 么 新 内 存 的 分 配 一 定 是 成 功 的 。 





2) 当 TCP 内 存在 tcp_mem[0] 与 tcp_mem[1] 之 间 时 ， 系 统 可 能 处 于 内 
存 压力 模式 ， 例 如 总 内 存 刚 从 tcp_mem[1] 之 上 下 来 ;也 可 能 是 在 非 压力 
模式 下 ， 例 如 总 内 存 刚 从 tcp_mem[0] 以 下 上 来 。 





此 时 ， 无 论 是 否 在 压力 模式 下 ， 只 要 TCP 连 接 所 用 缓存 未 超过 
tcp_rmem[0] 或 者 tcp_wmem[0]， 那 么 都 一 定 能 成 功 分 配 新 内 存 。 人 否则 ， 
基本 上 就 会 面临 分 配 失败 的 状况 。 (还 有 少量 例外 场景 允许 分 配 内 存 成 


功 ， 这 里 不 纠结 内 核 的 实现 细 市 ， 故 略 过 。) 


3) 当 TCP 内 存在 tcp_mem[1] 与 tcp_mem[2] 之 间 时 ， 系 统一 定 处 于 系 
统 压力 模式 下 。 行 为 与 情况 2 相同 。 


4) 当 TCP 内 存在 tcp_mem[2] 之 上 时 ， 所 有 的 新 TCP 绥 存 分 配 都 会 失 
败 。 







连接 已 用 缓存 是 否 超 过 缓存 上 限 ? 


TCP 总 内 存 是 否 小 于 tcp_mem[0]? 


是 否 超过 tcp_rmem[0| 或 者 tcp_wmem[0]? 


分 配 缓 存 成 功 分 配 缓存 失败 


图 9-11 Linux 下 TCP 缓 存 上 限 的 自 适 应 调整 


9.11 小结 


本 章 在 具体 的 事件 驱动 模块 基础 上 以 epoll 方 式 为 例 ， 完 整地 阐述 了 
Nginx 的 事件 驱动 机 制 ， 并 介绍 了 3 个 与 事件 驱动 密切 相关 的 Nginx 模 
块 ， 同 时 说 明了 事件 驱动 中 的 流程 是 如 何 执行 的 。 男 外 ， 还 介绍 了 
Nginx 在 局 并 发 服务 器 设计 上 的 一 些 拉 巧 ， 这 不 仅 对 我 们 了 解 Nginx 的 染 
构 有 所 帮助 ， 更 对 我 们 以 后 设计 独立 的 高 性 能 服务 器 有 非常 大 的 启发 意 
义 。 本 章 内 容 也 是 Nginx 其 他 模块 的 基础 ， 之 后 的 章节 都 是 在 讨论 事件 
消费 模块 ， 特 别 是 后 续 的 HTTP 模 块 ， 在 学 习 它 们 的 设计 方法 时 我 们 会 
经 常 性 地 返回 到 本 间 的 事件 驱动 机 制 中 。 





第 10 章 HTTP 框架 的 初始 化 


从 本 章 开 始 将 探讨 事件 消费 模块 的 “大 户 一 一 HITP 模 块 。Nginx 作 
为 Web 服 务 占 ， 其 HTTP 模 块 的 数量 远 超过 了 其 他 4 类 模块 (核心 模块 、 
事件 模块 、 配 置 模块 、 邮 件 模块 ) ， 其 代码 规模 也 同样 遥遥 领先 。 


这 些 实现 了 丰富 多 样 功能 的 HTTP 模 块 是 以 一 种 什么 样 的 方式 组 织 
起 来 的 呢 ? 它们 各 自 功能 的 高 度 可 定制 性 是 如 何 实现 的 ? 共性 在 哪里 ? 
Nginx 又 是 怎样 把 这 些 共性 的 内 容 提 取出 来 ， 并 以 一 个 强大 的 HTTP 框 架 
帮助 各 个 HITP 模 块 实现 具体 的 功能 呢 ? 


在 回答 这 些 问题 前 ， 先 来 回顾 一 下 本 书 的 第 二 部 分 ， 因 为 第 二 部 分 
始终 在 讲 如 何 开发 一 个 HTTP 模 块 ， 这 种 应 用 级 别 的 HTTP 模 块 就 是 由 
HTTP 框 架 定义 和 管理 的 。HTTP 框 架 大 致 由 1 个 核心 模块 

(ngx_http_module〉、 两 个 HTTP 模 块 (ngx_http_core_module、 
ngx_http_upstream_module) 组 成 ， 它 将 负 员 调度 其 他 HTTP 模 块 来 一 起 
处 理 用 户 请 求 。 下 面 先 来 弄 清楚 普通 的 HTTP 模 块 和 HTTP 框 架 各 自 的 天 
注 点 在 哪里 。 








先 来 看 第 3 章 ~ 第 5 章 例 子 中 的 HTTP 模 块 通常 会 做 哪些 工作 : 


1) 处 理 已 经 解析 完毕 的 HTTP 请 求 〈 也 就 是 第 二 部 分 中 反复 提 到 的 
填充 好 的 ngx_http_request_t 结 构 体 ) 。 





2) 获取 到 nginx.conf 里 自己 感 兴趣 的 配置 项 ， 无 论 它 们 是 否 同 时 出 
现在 不 同 的 http{} 配 置 块 、server{} 配 置 块 或 者 location{} 配 置 块 下 ， 都 需 
要 正确 地 解析 出 ， 以 此 决定 针对 不 同 的 用 户 请 求 定制 不 同 的 功能 


3) 调用 HTTP 框 染 提 供 的 方法 就 可 以 友 送 HTTP 啊 应 ， 包 括 使 用 磁 
盘 IO 读 取 数 据 并 发 送 。 


4) 将 一 个 请 求 分 为 顺序 性 的 多 个 处 理 阶段 ， 前 一 个 阶段 的 结果 会 
影响 后 一 个 阶段 的 处 理 。 例 如 ，ngx_http_access_module 模 块根 据 IP 信 息 
拒绝 一 个 用 户 请 求 后 ， 本 应 接着 执行 的 其 他 HITP 模 块 将 没有 机 会 再 处 
理 这 个 请 求 。 


5) 异步 接收 HITP 请 求 中 的 包 体 ， 可 以 将 网 络 数据 保存 到 磁盘 上 。 
6) 异步 访问 第 三 方 服务 。 


7) 分 解 出 多 个 子 请 求 来 构造 处 理 复杂 业务 的 能 力 ， 子 请 求 间 的 处 
理 仍 然 是 异步 化 、 非 阻 紧 的 。 





以 上 只 是 一 个 简单 粗略 的 总 结 ，HTTP 模 块 或 多 或 少 都 会 需要 这 些 
功能 。 以 这 些 功 能 为 例 ， 我 们 来 探讨 一 下 HTTP 框 架 至 少 要 完成 哪些 基 
础 性 的 工作 。 





1) 处 理 所 有 http{} 块 内 的 配置 项 ， 管 理 每 个 HTTP 模 块 感 兴趣 的 配 
置 项 (允许 同一 个 http{} 下 出 现 多 个 server{}、location{} 等 子 配 置 块 ， 允 


许 同 名 的 配置 项 同时 出 现在 各 种 配置 块 中 ) 。 





2) HTTP 框 架 要 能 够 使 用 第 9 章 介 绍 的 事件 模块 监听 Web 端 口 ， 并 
处 理 新 连接 事件 、 可 读 事 件 、 可 写 事件 等 。 








3) HTTP 框 架 需 要 有 状态 机 来 分 析 接 收 到 的 TCP 和 字符 流 是 否 是 完整 


的 HTTP 包 。 


4) HITP 框 架 能 够 根据 接收 到 的 HTTP 请 求 中 的 URI 和 HTTP 头 部 ， 
并 以 nginx.conf 中 server_name 和 ]location 等 配置 项 为 依据 ， 将 请 求 按照 其 
所 在 阶段 准确 地 分 发 到 某 一 个 HTTP 模 块 ， 从 而 调用 它 的 回调 方法 来 处 
理 该 请 求 。 


5) 问 HTTP 模 块 提供 必要 的 工具 方法 ， 可 以 处 理 网 络 WO〔( 读 取 
HTTP 包 体 、 发 送 HTTP 响 应 ) 和 磁盘 IO 。 


6) 提供 upstream 机 制 帮助 HTTP 模块 访问 第 三 方 服 务 。 


7) 提供 subrequest 机 制 帮 助 HTTP 模 块 实现 子 请 求 。 





HTTP 框 架 需 要 做 的 工作 很 多 ， 实 际 上 ，HITTP 的 框架 性 代码 也 是 极 
为 庞大 的 ， 为 了 简便 起 见 ， 本 书 以 后 的 章节 将 专注 在 HTTP 框 架 的 流程 
代码 中 ， 完 全 不 会 涉及 具体 的 HTTP 功 能 模块 ， 也 不 会 涉及 框架 中 不 太 
重要 的 工具 性 的 代码 。 











本 章 会 完整 地 介绍 ngx_http_module 模 块 ， 其 中 涉及 少量 
ngx_http_core_module 模 块 的 功能 。 因 为 构成 HTTP 框 架 的 几 个 模块 间 的 
代码 耦合 性 很 高 ， 所 以 对 于 HTTP 框架 的 介绍 并 不 会 按照 模块 进行 ， 而 
是 从 HTTP 框 架 的 功能 和 架构 上 进行 ， 其 中 本 章 介 绍 Nginx 启 动 过 程 中 
HTTP 框 架 是 怎样 初始 化 的 ， 第 11 章 介绍 Nginx 运 行 过 程 中 HTTP 框 架 是 
怎样 调度 HTTP 模 块 处 理 请 求 的 ， 第 12 章 讲述 访问 第 三 方 服务 的 upstream 
机 制 是 如 何 工作 的 。 


10.1 HTTP 框架 概述 


为 了 让 读者 对 HTTP 框 染 所 要 完成 的 工作 有 一 个 直观 的 认识 ， 本 章 
将 依托 一 个 贯穿 始终 的 nginx.conf 配 置 范 例 来 说 明 框架 的 行为 ， 如 下 所 





钞 。 
http { 
mytest_num 1; 
server { 


server_name A; 

listen 127.0.0.1:8000; 

listen 80; 

mytest_num 2， 

location /ZL1L { 
mytest_num 3; 


} 
location /L2 { 
mytest_num 4; 


} 


server { 
server_name B， 
listen 80; 
listen 8080; 
listen 173.39.160.51:8000; 
mytest_num 5; 
location /Li1 { 
mytest_num 6; 


} 
location /L3 { 
mytest_num 7; 





从 上 面 这 个 简单 的 例子 中 ， 可 以 获取 下 列 信 息 : 


* HTTP 框 架 是 支持 在 http{} 块 内 拥有 多 个 server{}、location{} 配 置 
块 的 。 


" 选择 使 用 哪 一 个 servet 虚 拟 主 机 块 是 取决 于 server_name 的 。 


. 任意 的 server 块 内 都 可 以 用 listen 来 监听 端口 ， 在 不 同 的 servet 块 内 
允许 监听 相同 的 端口 。 


选择 使 用 哪 一 个 location 块 是 将 用 户 请 求 URI 与 合适 的 servet 块 内 的 


所 有 location 表 达 式 做 匹配 后 决定 的 。 


` 同一 个 配置 项 可 以 出 现在 任意 的 http{}、server{}、location{} 等 配 
置 块 中 。 


HTTP 框 架 如 何 实 现 上 述 的 配置 项 特性 呢 ? 


HTTP 框 架 的 首要 任务 是 通过 调用 ngx_http_module_t 接 口中 的 方法 
来 管理 所 有 HTTP 模 块 的 配置 项 ，10.2 节 中 会 详细 描述 这 一 过 程 。 在 10.3 
节 中 ， 我 们 会 探讨 监听 端口 与 server 虚 拟 主机 间 的 关系 ， 包 括 它们 是 用 
何 种 数据 结构 关联 在 一 起 的 。 所 有 的 server 虚 拟 主机 会 以 散 列 表 的 数据 
结构 组 织 起 来 ， 以 达到 高 效 查 询 的 目的 ， 在 10.4 节 中 会 介绍 这 一 过 程 。 





所 有 的 location 表 达 式 会 以 一 个 静态 的 二 又 查找 树 组 织 起 来 ， 以 达到 高 
效 查 询 的 目的 ， 在 10.5 节 中 会 说 明 它 。 对 于 每 一 个 HITP 请 求 ， 都 会 以 
流水 线形 式 划 分 为 多 个 阶段 ， 以 供 HTTP 模 块 插 入 到 HTTP 框 架 中 来 共同 
处 理 请 求 ，10.6 节 中 会 说 明 这 些 阶段 划分 、 实 现 的 依据 所 在 。 在 10.7 节 
中 ， 将 会 完整 地 说 明 在 Nginx 启 动 过 程 中 ，HTTP 框 架 是 如 何 初 始 化 的 。 








下 面 开 始 介 绍 ngx_http_module_t 接 口 的 相关 内 容 。 


ngx_http_module 核 心 模块 定义 了 新 的 模块 类 型 
NGX_HTTP_MODULE。 这 样 的 HTTP 模 块 对 于 ctx 上 下 文 使 用 了 不 同 于 
核心 模块 、 事 件 模块 的 新 接口 ngx_http_module t， 虽 然 第 3 章 中 曾经 提 
到 过 ngx_http_module _t 接 口 的 定义 ， 但 那 时 我 们 介绍 的 角度 是 如 何 开发 
一 个 HTTP 模块 ， 现 在 探讨 实现 HTTP 框架 时 ， 对 ngx_http_module_t 接 口 
的 解读 就 不 同 了 。 在 重新 解读 ngx_http_module t 接 口 之 前 ， 先 对 不 同 级 
别 的 HTTP 配置 项 做 个 缩 写 名 词 的 定义 : 





直接 素 属 于 http{} 块 内 的 配置 项 称 为 main 配 置 项 。 

" 直接 隶属 于 server 人 } 块 内 的 配置 项 称 为 stv 配 置 项 。 

" 直接 隶属 于 location{} 块 内 的 配置 项 称 为 loc 配 置 项 。 

其 他 配置 块 本 章 不 会 涉及 ， 因 为 它们 与 HTTP 框 染 没 有 任何 关系 。 


对 于 每 一 个 HTTP 模 块 ， 都 必须 实现 ngx_http_module_t 接 口 。 下 面 


将 从 HITP 框 娘 的 角度 来 进行 重新 解读 ， 如 下 所 示 。 





typedef struct { 
// 在 解析 


http{...} 内 的 配置 项 前 回调 


ngx_int_t (*preconfiguration)(ngx_conf_t *cf); 
// 解析 完 


httpf{...} 内 的 所 有 配置 项 后 回调 


ngx_int_t (*postconfiguration)(ngx_conf_t *cf); 
/* 创 建 用 于 存储 


HTTP 全 局 配置 项 的 结构 体 ， 该 结构 体 中 的 成 员 将 保存 直属 于 


http{]} 块 的 配置 项 参数 。 它 会 在 解析 


main 配 置 项 前 调用 


*/ 
void *(*create main conf)(ngx_conf_t *cf); 
// 解析 完 
main 配 置 项 后 回调 
char *(*init main conf)(ngx_conf_t *cf, void *conf); 
/* 创 建 用 于 存储 可 同时 出 现在 
main、 


Srv 级 别 配置 项 的 结构 体 ， 该 结构 体 中 的 成 员 与 


SerVver 配 置 是 相关 联 的 


4 
void *(*create srv_conf)(ngx_conf_t *cf); 
/*create_srv_conf 产生 的 结构 体 所 要 解析 的 配置 项 ， 可 能 同时 出 现在 


main、 


Srv 级 别 中 ， 


merge_srv_conf 方 法 可 以 把 出 现在 


main 级 别 中 的 配置 项 值 合并 到 


Srv 级 别 配 置 项 中 


*/ 
char *(*merge_srv_conf)(ngx_conf_t *cf, void *prev, void *conf); 
/* 创 建 用 于 存储 可 同时 出 现在 


main、 


Srv、 


0C 级 别 配置 项 的 结构 体 ， 该 结构 体 中 的 成 员 与 


location 配 置 是 相关 联 的 


4 
void *(*create loc _ conf)(ngx_conf_t *cf); 
/*create_loc_conf 产 生 的 结构 体 所 要 解析 的 配置 项 ， 可 能 同时 出 现在 


main、 


Srv、 


0C 级 别 中 ， 


merge_loc_conf 方 法 可 以 分 别 把 出 现在 


main、 


SrV 级 别 的 配置 项 值 合并 到 


loc 级 别 的 配置 项 中 


*/ 
char *(*merge_ loc conf)(ngx_conf_t *cf, void *prev, void *conf ) ， 
} ngx_http_module_t; 


可 以 看 到 ，ngx_http_module_t 接 口 完全 是 围绕 着 配置 项 来 进行 的 ， 
这 与 第 8 章 提 到 过 的 可 定制 性 、 可 扩展 性 等 架构 特性 是 一 致 的 。 每 一 个 
HTTP 模 块 都 将 根据 main、srv、loc 这 些 不 同 级 别 的 配置 项 来 决定 自己 的 
行为 。 





10.2 ”管理 HTTP 模 块 的 配置 项 





上 文 介绍 过 事件 配置 项 的 管理 ， 其 实 HTTP 配 置 项 的 管理 与 事件 模 
块 有 些 相 似 ， 但 由 于 它 具 有 3 种 不 同 级 别 配 置 项 ， 所 以 管理 要 复杂 许 
多 。 对 于 HTTP 模 块 而 言 ， 只 需 关 心 工 作 时 能 够 取 到 正确 的 配置 项 。 但 
对 于 HTTP 框 架 而 言 ， 任 何 一 个 HTTP 模 块 的 server 相 关 的 配置 项 都 是 可 
能 出 现在 main 级 别 中 ， 而 location 相 关 的 配置 项 可 能 出 现在 main、srv 级 
别 中 。 而 server 是 可 能 存在 许多 个 的 ，location 更 是 可 以 反复 租 套 的 ， 这 
样 就 要 为 每 个 HTTP 模 块 按照 nginx.conf 里 的 配置 块 建立 许多 份 配置 。 在 
10.1 节 的 例子 中 ， 共 出 现 了 7 个 配置 块 ， 对 于 HTTP 框架 而 言 ， 就 需要 为 
所 有 的 HTTP 模 块 分 配 7 个 用 于 存储 配置 结构 体 指针 的 数组 。 











在 处 理 http{} 块 内 的 main 级 别 配置 项 时 ， 对 每 个 HTTP 模 块 来 说 ， 都 
会 调用 create_main_conf、create_srv_conf、create_loc_conf 方 法 建立 3 个 
结构 体 ， 分 别 用 于 存储 HITP 全 局 配置 项 、server 配 置 项 、location 配 置 
项 。 现 在 问题 来 了 ，http{} 内 的 配置 项 明明 就 是 main 级 别 的 ， 有 了 
create_main_conf 生 成 的 结构 体 已 经 足够 保存 全 局 配置 项 参数 了 ， 为 什么 
还 要 调用 create_Srv_conf、create_loc_conf 方 法 建立 结构 体 呢 ? 其 实 ， 这 
是 为 了 把 同时 出 现在 http{}、server{}、location{} 内 的 相同 配置 项 进行 合 
并 而 做 的 准备 。 假 设 有 一 个 与 server 相 关 的 配置 项 (例如 负责 指定 每 个 
TCP 连 接 上 内 存 池 大 小 的 connection_pool_size 配 置 项 ) 同时 出 现在 


http{}、server{} 中 ， 那 么 对 它 感 兴趣 的 HTTP 模 块 就 有 权 决 定 srv 结 构 体 
内 的 成 员 完 竟 是 以 main 级 别 配 置 项 为 准 ， 还 是 srv 级 别 配 置 项 为 准 。 结 
合 10.1 节 的 例子 来 看 ，mytest_num 出 现在 http{} 下 时 参数 为 1， 出 现在 
server A{} 下 时 参数 为 2， 那 么 ，mytest 模 块 就 有 权 决 定 ， 当 人 处理 server A 
虚拟 主机 时 ， 究 竟 是 把 mytest_num 参 数 当 做 1 还 是 2， 或 者 把 它们 俩 相 
加 ， 这 都 是 任何 一 个 HTTP 模块 的 目 由 。 对 于 HTTP 框架 而 言 ， 在 解析 
main 级 别 的 配置 项 时 ， 必 须 同 时 创建 3 个 结构 体 ， 用 于 合并 之 后 会 解析 
到 的 server、location 相 关 的 配置 项 。 


对 于 server{} 块 内 配置 项 的 处 理 ， 需 要 调用 每 个 HTTP 模 块 的 
create_srv_conf 方 法 、create_loc_conf 方 法 建立 两 个 结构 体 ， 分 别 用 于 存 
储 server、location 相 关 的 配置 项 ， 其 中 create_loc_conf 产 生 的 结构 体 仅 用 
于 合并 location 相 关 的 配置 项 。 


对 于 location 块 内 配置 项 的 处 理 则 简单 许多 ， 只 需要 调用 每 个 HTTP 
模块 的 create_loc_conf 方 法 建立 1 个 结构 体 即 可 。 





结合 10.1 市 中 nginx.conf 配 置 文件 的 厂 断 来 看 ， 实 际 上 HTTP 框 架 最 
多 必须 为 一 个 HTTP 模 块 〈 如 mytest 模 块 ) 创建 3+2+1+1+2+1+1=11 个 配 
置 结构 体 ， 而 经 过 合并 后 实际 上 每 个 HTTP 模块 会 用 到 的 结构 体 有 7 个 。 
可 为 什么 mytest 模 块 使 用 ngx_http_mytest_conf t 结 构 体 时 好 像 只 有 1 个 配 
置 结构 体 呢 ? 因为 在 HITP 框 架 处 理 到 某 个 阶段 时 ， 例 如 ， 在 寻找 到 适 
合 的 location 前 ， 如 果 试 图 去 取 ngx_http_mytest_conf t 结 构 体 ， 得 到 的 将 





是 srv 级 别 下 的 配置 ， 而 寻找 到 ]ocation 后 ，ngx_http_mytest_conf t 结 构 
体 中 的 成 员 将 是 loc 级 别 下 的 配置 。 





下 面 介绍 一 下 ngx_http_module 模 块 在 实现 上 是 如 何 体现 上 述 思 路 
的 。 


10.2.1 管理 main 级 别 下 的 配置 项 


上 文 说 过 ， 在 解析 HTTP 模 块 定义 的 main 级 别 配 置 项 时 ， 将 会 分 别 
调用 每 个 HTTP 模 块 的 create_main conf、create_srv_conf、 
create_loc_conf 方 法 建立 3 个 结构 体 ， 分 别 用 于 存储 全 局 、server 相 关 
的 、location 相 关 的 配置 项 ， 但 它们 守 竟 是 以 何 种 数据 结构 保存 的 呢 ? 
与 核心 结构 体 ngx_cycle _t 中 的 conf_ctx 指 针 又 有 什么 样 的 关系 呢 ? 在 图 
10-10 中 的 第 2 步 ~ 第 7 步 包 含 了 解 机 main 级别 配置 项 的 所 有 流程 ， 而 图 
10-1 将 会 展现 它们 在 内 存 中 的 布局 ， 可 以 看 到 ， 其 中 
ngx_http_core_module 模 块 完成 了 HTTP 框 架 的 大 部 分 功能 ， 而 它 又 是 第 
1 个 HTTP 模 块 ， 因 此 ， 它 使 用 到 的 3 个 结构 体 


(ngx_http_core_ main conf t、 ngx_http_core_srv_conf t、 











ngx_http_core_loc_conf t) 也 是 用 户 非 稼 关心 的 。 


图 10-1 中 有 一 个 结构 体 叫 做 ngx_http_conf_ctx_t， 它 是 HTTP 框架 中 
一 个 经 常用 到 的 数据 结构 ， 下 面 看 看 它 的 定义 。 


typedef struct { 
/* 指 向 一 个 指针 数组 ， 数 组 中 的 每 个 成 员 都 是 由 所 有 


HTTP 模 块 的 


create_main_conf 方 法 创建 的 存放 全 局 配置 项 的 结构 体 ， 它 们 存放 着 解析 直属 


http{} 块 内 的 


main 级 别 的 配置 项 参数 


4 
void **main_conf; 
/* 指 向 一 个 指针 数组 ， 数 组 中 的 每 个 成 员 都 是 由 所 有 


HTTP 模 块 的 


Ccreate_srv_conf 方 法 创建 的 与 


Server 相 关 的 结构 体 ， 它 们 或 存放 


main 级 别 配 置 项 ， 或 存放 


SrVv 级 别 配置 项 ， 这 与 当前 的 


ngx_http_conf_ctx_t 是 在 解析 





http{ 了 或 者 


Server{} 块 时 创建 的 有 关 


2 
void **srv_conf; 
/* 指 向 一 个 指针 数组 ， 数 组 中 的 每 个 成 员 都 是 由 所 有 


HTTP 模 块 的 


create_1oc_conf 方 法 创建 的 与 


location 相 关 的 结构 体 ， 它 们 可 能 存放 着 


main、 


Srv、 


loc 级 别 的 配置 项 ， 这 与 当前 的 


ngx_http_conf_ctx_t 是 在 解析 





http{}、 


Server{} 或 者 


location{} 块 时 创建 的 有 关 


*/ 
void **]loc_conf; 
} ngx_http_conf_ctx_t; 








ngx_http_conf_ctx_t 中 仅 有 3 个 成 员 ， 它 们 分 别 指向 3 个 指针 数组 。 
在 10.2.4 节 中 ， 读 者 会 看 到 srv_conf 数 组 和 loc_conf 数 组 在 配置 项 的 合并 
操作 中 是 如 何 使 用 的 。 





在 核心 结构 体 ngx_cycle_t 的 conf_ctx 成 员 指 向 的 指针 数组 中 ， 第 7 个 
指针 由 ngx_http_module 模 块 使 用 (ngx_http_module 模 块 的 index 序 号 为 
6， 由 于 由 0 开始 ， 所 以 它 在 ngx_modules 数 组 中 排行 第 7。 在 存放 全 局 配 
置 结构 体 的 conf_ctx 数 组 中 ， 第 7 个 成 员 指 向 ngx_http_module 模 块 )， 这 
个 指针 设置 为 指向 解析 http{} 块 时 生成 的 ngx_http_conf_ctx_t 结 构 体 ， 而 
ngx_http_conf_ctx_t 的 3 个 成 员 则 分 别 指向 新 分 配 的 3 个 指针 数组 。 新 的 

旨 针 数组 中 成 员 的 意义 由 每 个 HTTP 模 块 的 ctx_index 序 号 指定 
Cctx_index 在 HITP 模 块 中 表明 它 处 于 HTTP 模块 间 的 序号 ) ， 例 如 ， 第 
6 个 HTTP 模 块 的 ctx_index 是 5〈ctx_index 同 样 由 0 开始 计数 ) ， 那 么 在 


ngx_http_conf_ctx_t 的 3 个 数组 中 ， 第 6 个 成 员 就 指 同 第 6 个 HTTP 模 块 的 
create_ main conf、create srv_conf、create loc conf 方 法 建立 的 结构 体 ， 


当然 ， 如 果 相 应 的 回调 方法 没有 实现 ， 该 指针 就 为 NULL 空 指针 。 





ngx_cycle t 


所 有 核心 模块 的 配置 结构 体 指针 


的 conf_ctx 


| ngx_modules 数 组 可 以 看 出 ， 第 7 个 模块 是 
ngx_http_module 模 块 ，conf_ctx 数 组 中 第 7 位 存储 


着 Ngx_http_module 模 块 的 配置 项 指针 ， 在 这 里 ， 
这 个 指针 被 定义 为 指向 ngx_http_conf_ctx_t 结 构 体 





ngx_http_conf_ctx_t 结 构 体 


a ngx_http_c ‘Ore_main_cc Onf 上 
DE 





create_main _conf 


生成 的 结构 体 指针 







create_srv_conf 


生成 的 结构 体 指针 


贿 国 醒 国 故 阐 国 第 6 个 HTTP 模 块 create_main_conf_t 结 构 体 


create_loc_conf 


生成 的 结构 体 指 针 





第 6 个 HTTP 模 块 create_srv_conf_t 结 构 体 


第 6 个 HTTP 模 块 create_loc_conf _t 结 构 体 





图 10-1 HTTP 框 架 解 析 main 级 别 配置 项 时 配置 结构 体 的 内 存 示 意图 


ngx_http_core_module 模 块 是 第 1 个 HTTP 模 块 ， 它 的 ctx_index 序 号 


是 0， 因 此 ， 数 组 中 的 第 1 个 指针 将 指向 ngx_http_core_module 模 块 生成 
ngx_http_core_main_conf t、 ngx_http_core_srv_conf t、 


ngx_http_core_loc_conf _t 结 构 体 。 


可 如 何 由 ngx_cycle_ t 核 心 结构 体 中 找到 main 级 别 的 配置 结构 体 呢 ? 
Nginx 提 供 的 ngx_http_cycle_get_ module_main_conf 宏 可 以 实现 这 个 功 
能 ， 如 下 所 示 。 





#define ngx_http_cycle get module main conf(cycle, module) \ 
(cycle->conf_ctx[ngx_http_module.index] \ 
((ngx_http_conf_ctx_t *) 
cycle->conf_ctx[ngx_http_module.index]) 
->main_conf[module.ctx_index]: \ 
NULL) 











其 中 参数 cycle 是 ngx_cycle_t 核 心 结构 体 指 针 ， 而 module 则 是 所 要 操 
作 的 HTTP 模 块 。 它 的 实现 很 简单 ， 先 由 cycle 的 conf_ctx 指 针 数 组 中 找到 
ngx_http_module.index 序 号 〈 上 文 说 过 ， 其 index 为 6) 对 应 的 指针 ， 获 
取 到 http{} 块 下 的 ngx_http_conf_ctx_ ft 成员， 然后 经 由 main_conf 数 组 即 可 
找到 所 有 HTTP 模 块 的 main 级 别 配置 结构 体 。 最 后 ， 根 据 所 要 查询 的 
module 数 组 的 ctx_index 序 号 取得 其 main 级 别 下 的 配置 结构 体 ， 例 如 : 





ngx_http_perl main conf_t *pmcf = ngx_http_cycle get module main conf(cycle, ngx_ht 











er 注意 HTTIP 全 局 配置 项 是 基础 ， 管 理 server、location 等 配置 块 


时 取决 于 ngx_http_core_module 模 块 出 现在 main 级 别 下 存储 全 局 配置 项 的 


ngx_http_cote_main_conf t 结 构 体 。 


10.2.2 ”管理 Server 级 别 下 的 配置 项 


在 解析 main 级 别 配 置 项 时 ， 如 果 发 现 了 server{f} 配 置 项 ， 惑 会 回调 
ngX_http_core_server 方 法 〈 该 方法 属于 ngx_http_core _ module 模块 ) ， 而 
在 这 个 方法 里 则 会 开始 解析 srv 级 别 的 配置 项 ， 其 流程 如 图 10-2 所 示 。 


下 面 简要 说 明 图 10-2 中 的 步 又 : 


1) 在 解析 到 server 块 时 ， 首 先 会 像 解析 http 块 一 样 ， 建 立 属于 这 个 
server 块 的 ngx_http_conf_ctx_t 结 构 体 。 在 ngx_http_conf_ctx_t 的 3 个 成 员 
中 ，main_conf 将 指向 所 属 的 http 块 下 ngx_http_conf_ctx_t 结 构 体 的 
main_conf 指 针 数 组 ， 而 srv_conf 和 loc_conf 都 将 重新 分 配 指针 数组 ， 数 
组 的 大 小 为 ngx_http_max_module， 也 就 是 所 有 HTTP 模 块 的 总 数 。 


2) 循环 调用 所 有 HTTP 模 块 的 create_srv_conf 方 法 ， 将 返回 的 结构 
体 指 针 按照 模块 序号 ctx_index 保 存 到 上 述 的 srv_conf 指 针 数 组 中 。 


3) 循环 调用 所 有 HTTP 模 块 的 create_ loc_conf 方 法 ， 将 返回 的 结构 
体 指 针 按照 模块 序号 ctx_index 保 存 到 上 述 的 loc_conf 指 针 数 组 中 。 


4) 第 1 个 HTTP 模 块 就 是 ngx_http_core_module 模 块 ， 它 在 
create_SsrV_conf 方 法 中 将 会 生成 非常 关键 的 ngx_http_core_srv_conf t 配 置 





结构 体 ， 这 个 结构 体 对 应 着 当前 正在 解析 的 server 块 ， 这 时 ， 将 
ngx_http_core_srv_conf _t 添 加 到 全 局 的 ngx_http_core_main_conf t 结 构 体 
的 servers 动 态 数组 中 ， 在 图 10-3 中 会 看 到 这 一 点 。 


1 ) 分 配 存 放 srv 级 别 配置 项 指针 的 
两 个 数组 


2 ) 调用 所 有 HTTP 模 块 的 


create _Srv_conf 方法 


3 ) 调用 所 有 HTTP 模 块 的 


create loc_con{ 方 法 


4) 将 属于 当前 server 块 的 ngx_http _core_srv_conf_1 
添加 到 servers 动态 数组 中 


5 ) 解析 当前 server 块 下 的 全 部 
sr 级 别 配置 项 


6 ) 如 果 没 有 listen 选项， 则 监听 
默认 的 80 端 口 


y 


图 10-2 解析 server{} 块 内 配置 项 的 流程 





5) 解析 当前 server{} 块 内 的 所 有 配置 项 。 





6) 如 末 在 server{} 块 内 没有 解析 到 listen 配 置 项 ， 则 意味 着 当前 的 
server 虚 拟 主机 并 没有 监听 TCP 端 口 ， 这 不 符合 HTTP 框 架 的 设计 原则 。 
于 是 将 开始 监听 默认 端口 80， 实 际 上 ， 如 果 当 前 进程 没有 权限 监听 1024 
以 下 的 端口 ， 则 会 改 为 监听 8000 端 口 。 


由 于 http 块 只 有 1 个 ， 因 此 在 10.2.1 节 中 可 以 简单 地 给 出 main 级 别 配 
置 项 的 内 存 示 意图 。 但 http 块 内 会 包含 任意 个 server 块 ， 对 于 每 个 server 
块 都 需要 建立 1 个 ngx_http_conf_ctx_t 结 构 体 ， 这 些 server 块 的 
ngx_http_conf_ctx_t 结 构 体 是 通过 ngx_array_t 动 态 数 组 组 织 起 来 的 ， 这 其 
中 的 关系 就 比较 复杂 了 ， 图 10-3 是 它们 简单 的 内 存 示 意图 。 


ngx_cycle 1 


所 有 核心 模块 的 配置 结构 体 指针 1 


ngx_http conf_ctx tt 结构 体 
加 画 本 师 | 男 醒 夯 国 大 辆 
本 









ngx_http_core_main_conf tt 


SeIVeTS 












http 块 下 create_main__conf 配置 项 指针 


servers 数 组 中 指针 皆 指 回 属于 server A 块 


ngx_http _core _srv _conf 上 
PP | ngx_http_core_srv_conf_t 


ss ” 
server A 块 下 


ngx_http_conf_ctx_t 结 构 体 
LILLLILIRdes 


server A 块 下 各 模块 
create_srv_conf 生成 的 结构 体 指 针 


画 画 而 本 徊 状 夯 加 男 醒 ee 
ARP gx—http_core_srv_—cont-1 
server A 块 下 各 模块 
create_loc_conf 生 成 的 结构 体 指 针 


server B 块 下 ngx_http_conf_ctx_t 结 构 体 









图 10-3 ” HTTP 模块 Srv 级别 配置 项 结构 体 指 针 的 内 存 示 意 








图 10-3 是 针对 10.1 节 中 的 例子 所 画 的 示意 图 ， 在 http 块 下 有 两 个 


server 块 ， 分 别 表示 虚拟 主机 名 为 A 的 配置 块 和 虚拟 主机 名 为 B 的 配置 
块 。 解 析 每 一 个 server 块 时 都 会 创建 一 个 新 的 ngx_http_conf_ctx_t 结 构 
体 ， 其 中 的 main_conf 将 指向 http 块 下 main_conf 指 针 数 组 ， 而 srv_conf 和 
loc_conf 数 组 则 都 会 重新 分 配 ， 它 们 的 内 容 就 是 所 有 HTTP 模 块 的 
create_srv_conf 方 法 、create_loc_conf 方 法 创建 的 结构 体 指 针 。 


在 10.2.1 节 中 提 到 的 main 级 别 配置 项 中 ，ngx_http_core_module 模 块 
的 ngx_http_core_main_conf t 结 构 体 中 有 一 个 servers 动 态 数组 ， 如 下 所 


钞 。 





typedef struct { 
/* 存 储 指 针 的 动态 数组 ， 每 个 指针 指向 


ngx_http_core_srv_conf_t 结 构 体 的 地 址 ， 也 就 是 其 成 员 类 型 为 





ngx_http_core_srv_conf_t** */ 
ngx_array_t servers,; 





} ngx_http_core_ main conf_t; 








servers 动 态 数 组 中 的 每 一 个 元 素 都 是 一 个 指针 ， 它 指向 用 于 表示 
server 块 的 ngx_http_core_srv_conf t 结 构 体 的 地 址 (属于 
ngx_http_core_module 模 块 )。ngx_http_core_srv_conf t 结 构 体 中 有 1 个 
ctx 指 针 ， 它 指 癌 解析 server 块 时 新 生成 的 ngx_http_conf_ctx_t 结 构 体 ， 具 
体 如 下 所 示 。 





typedef struct { 


// 指向 当前 


Server 块 所 属 的 





ngx_http_conf_ctx tt 结构 体 


ngx_http_conf_ctx_t *ctx; 
/当前 





Server 块 的 虚拟 主机 名 ， 如 果 存 在 的 话 ， 则 会 与 


HTTP 请 求 中 的 


Host 头 部 做 匹配 ， 匹 配 上 后 再 由 当前 





ngx_http_core_srv_conf_t 处 理 请 求 


* 
ngx_str_t server_name ; 


} ngx_http_core_srv_conf_t; 








这 样 ，server 块 下 以 ngx_http_conf_ctx_t 组 织 起 来 的 所 有 配置 项 结构 
体 ， 就 会 由 servers 动 态 数组 关联 起 来 。servers 动 态 数 组 中 的 元 素 个 数 与 
http 块 下 的 server 配 置 块 个 数 是 一 致 的 。 


10.2.3 ”管理 location 级 别 下 的 配置 项 


在 解析 srv 级 别 配 置 项 时 ， 如 有 末 发 现 了 location{} 配 置 块 ， 就 会 回调 
ngx_http_core_location 方 法 〈 访 方法 属于 ngx_http_core_module 模 块 ) ， 
在 这 个 方法 里 则 会 开始 解析 loc 级 别 的 配置 项 ， 其 流程 如 图 10-4 所 示 。 


下 面 简要 介绍 一 下 图 10-4 中 的 流程 : 


1) 在 解析 到 location{} 配 置 块 时 ， 仍 然 会 像 解 析 http 块 一 样 ， 先 建 
Yngx_http_conf_ctx_t 结 构 体 ， 只 是 这 里 的 main_conf 和 srv_conf 都 将 指向 
所 属 的 server 块 下 ngx_http_conf_ctx_t 结 构 体 的 main_conf 和 srv_conf 指 针 
数组 ， 而 loc_conf 则 将 指向 重新 分 配 的 指针 数组 。 


2) 循环 调用 所 有 HTTP 模 块 的 create_ loc_conf 方 法 ， 将 返回 的 结构 
体 指针 按照 模块 序号 ctx_index 保 存 到 上 述 的 loc_conf 指 针 数 组 中 。 


3) 如 果 在 location 中 使 用 了 正则 表达 式 ， 那 么 这 时 将 调用 
pcre_compile 方 法 预 编 译 正 则 表达 式 ， 以 提高 性 能 。 


4) 第 1 个 HTTP 模 块 是 ngx_http_core_module 模 块 ， 它 在 
create_loc_conf 方 法 中 将 会 生成 ngx_http_core_loc_conf t 配 置 结构 体 ， 可 
以 认为 该 结构 体 对 应 着 当前 解析 的 location 块 。 这 时 会 生成 
ngx_http_location_queue_t 结 构 体 ， 因 为 每 一 个 ngx_http_core_ loc_conf t 
结构 体 都 对 应 着 1 个 ngx_http_location_queue_t， 因 此 ， 此 处 将 把 
ngx_http_location_queue_t 串 联 成 双 回 链表 ， 在 图 10-5 中 会 看 到 这 一 点 。 














1 ) 分 配 用 于 存放 loc 级 别 配置 项 指针 的 1 个 数组 














2 ) 调用 上 所 有 模块 的 create _loc_conf 方 法 


[当前 location 后 的 表达 式 是 否 使 用 正则 表达 式 ] 


[使 用 了 正则 表达 式 ] 


3 ) 预 编译 正则 表达 式 


4) 建立 ngx_http _location_queuet 并 添加 到 双 回 链表 





5) 解 析 4 亲 location 下 的 所 有 loc 级 别 | 琴 C 置 项 


图 10-4 ”解析 location{} 配 置 块 的 流程 


5) 解析 当前 location{} 配 置 块 内 的 loc 级 别 配 置 项 。 


[没有 使 用 正则 表达 式 ] 


图 10-5 为 HTTP 模 块 loc 级 别 配 置 项 结构 体 指 针 的 内 存 示 意图 。 








图 10-5 仍 然 是 依据 10.1 节 中 的 配置 块 例子 所 画 的 示意 图 ， 不 过 ， 这 
里 仅 涉及 server 块 A〈 其 server_name 的 参数 值 为 A) 以 及 它 所 属 的 
location L1 块 。 在 解析 http 块 时 曾 创 建 过 1 个 ngx_http_core_loc_conf t 结 构 
体 〈 见 10.2.1 节 ) ， 在 解析 server 块 A 时 曾经 创建 过 1 个 
ngx_http_core_loc_conf t 结 构 体 〈 见 10.2.2 节 ) ， 而 解析 其 下 的 location 
块 L1 时 也 创建 了 ngx_http_core_loc_conf t 结 构 体 ， 从 图 10-5 中 可 以 看 出 
这 3 个 结构 体 间 的 关系 。 下 面 先 看 看 网 10-5 中 ngx_http_core_ loc_conf tt 的 
3 个 关键 成 员 : 





typedef struct ngx_http_core_loc conf_s ngx_http_core_ loc conf_t; 
struct ngx_http_core loc conf_s { 
// location 的 名 称 ， 即 








nginx.conf 中 


Jocation 后 的 表达 式 


ngx_str_t name; 
/* 指 向 所 属 


]ocation 块 内 


ngx_http_conf_ctx_t 结 构 体 中 的 





loc_conf 指 针 数 组 ， 它 保存 着 当前 


location 块 内 所 有 


HTTP 模 块 


Create_1oc_conf 方 法 产生 的 结构 体 指针 


2 
void **]loc_conf; 


/* 将 同一 个 


Server 块 内 多 个 表达 


]ocation 块 的 


ngx_http_core_loc_conf_t 结 构 体 以 双向 链表 方式 组 织 起 来 ， 该 





locations 指 针 将 指向 
ngx_http_location_queue_t 结 构 体 
*/ 


ngx_queue t *locations; 


下 






servers 数组 中 指针 皆 指 回 


ngx_http _core _srv _conf _1 


I ES TE BE Bs 0 EE I 
OR 


server A 块 下 create Joc_conf 


生成 的 结构 体 指针 


on | Sea | wa | 


Ng 
location L 1 抉 下 ngx_http_conf_ctx_t 结 构 体 


属于 location Ll 块 


a 
(Nl ED | 
B= 


location L 1 块 下 create_loc_conf 生 成 的 结构 体 指针 


图 10-5 ” HTTP 模块 loc 级 别 配置 项 


所 有 核心 模块 的 配置 结构 体 指 针 


http 块 下 create_main_conf 配置 项 指针 


server A 抉 下 


Se 


ngx_cycle_t 


conf _ctx 








ngx_http_core_main_conf_t 


SerTVETS 


ngx_http_core_srv_conf_t 


入 
Ee 


rver A 块 下 create_srv 


_conf 生成 的 结构 体 指 针 


ngx_http_core_loc_conf_t 


loc_conf 


ngx_http_core_loc_conf t 


loc_conf 


构 体 指 针 的 内 存 示意 图 
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可 以 这 么 说 ，ngx_http_core_loc_conf_t 拥 有 足够 的 信息 来 表达 1 个 
location 块 ， 它 的 loc_conf 成 员 也 可 以 引用 到 各 HTTP 模 块 在 当前 location 
块 中 的 配置 项 。 所 以 ,一旦 通过 某 种 容器 将 ngx_http_core_loc_conf t 组 
织 起 来 ， 也 就 是 把 location 级 别 的 配置 项 结构 体 管理 起 来 了 。 但 
ngx_http_core_loc_conf { 又 是 放置 在 什么 样 的 容器 中 呢 ? 注意 ， 图 10-3 
在 解析 server 块 A 时 有 1 个 ngx_http_core_loc_conf t 结 构 体 ， 它 的 地 位 与 
server 块 A 内 的 各 个 location 块 对 应 的 ngx_http_core_loc_conf t 结 构 体 是 不 
同 的 ，location L1、location L2 块 内 的 ngx_http_core_loc_conf t 是 通过 
server A 块 内 产生 的 ngx_http_core_loc_conf t 关 联 起 来 的 。 


在 ngx_http_core_loc_conf t 结 构 体 中 有 一 个 成 员 locations， 它 表示 属 
于 当前 块 的 所 有 1location 块 通过 ngx_http_location_queue_t 结 构 体 构成 的 双 
问 链 表 ， 如 下 所 示 。 





typedef struct { 
/*queue 将 作为 


ngx_queue 七 双向 链表 容器 ， 从 而 将 


ngx_http_location_queue_t 结 构 体 连接 起 来 


类 六 
ngx_queue_t queue; 
/* 如 果 


location 中 的 字符 串 可 以 精确 匹配 (包括 正则 表达 式 ) ， 


exact 将 指向 对 应 的 


ngx_http_core_loc_conf_t 结 构 体 ， 否 则 值 为 





NULL*/ 
ngx_http_core_loc conf_t *exact; 
/* 如 果 





location 中 的 字符 串 无 法 精确 匹配 (包括 了 自 定义 的 通配符 ) ， 


jnclusive 将 指向 对 应 的 


ngx_http_core_loc_conf_t 结 构 体 ， 否 则 值 为 





NULL*/ 
ngx_http_core_loc conf_t *inclusive,; 
// 指向 





location 的 名 称 


ngx_str_t *name; 


} ngx_http_location_queue_t; 





可 以 看 到 ，ngx_http_location_queue_t 中 的 queue 成 员 将 把 所 有 相关 
的 ngx_http_location_queue_t 结 构 体 串联 起 来 。 同 时 ， 
ngx_http_location_queue t 将 帮助 用 户 把 所 有 的 location 块 与 其 所 属 的 
server 块 关联 起 来 。 


那么 ， 哪 些 ngx_http_location_queue_t 结 构 体 会 被 串联 起 来 呢 ? 还 是 
看 10.1 市 的 例子 ，server 块 A 以 及 其 下 所 属 的 location L1 和 1location L2 共 包 
括 3 个 ngx_http_core_loc_conf t 结 构 体 ， 它 们 是 相关 的 ， 下 面 看 看 它们 是 
怎样 关联 起 来 的 ， 如 图 10-6 所 示 。 





每 一 个 ngx_http_core_loc_conf t 都 将 对 应 着 一 个 


ngx_http_location_queue_t 结 构 体 。 在 server 块 A 拥有 的 
ngx_http_core_loc_conf t 结 构 体 中 ，locations 成 员 将 指 癌 它 所 属 的 
ngx_http_location_queue_t 结 构 体 ， 这 是 1 个 双 同 链表 的 首部 。 当 解析 到 
location L1 块 时 ， 会 创建 一 个 ngx_http_location_queue_t 结 构 体 并 添加 到 
locations 双 向 链表 的 尾部 ， 该 ngx_http_location_queue_t 结 构 体 中 的 exact 
或 者 inclusive 指 针 将 会 指向 location LI 所属 的 ngx_http_core_loc_conf t 结 
构 体 《在 location 后 的 表达 式 属于 完全 匹配 时 ，exact 指 针 有 效 ， 人 否则 表 
达 式 将 带 有 通 配 答 ， 这 时 inclusive 有 效 。exact 优 先 级 高 于 inclusive) ， 
这 样 就 把 location L1 块 对 应 的 ngx_http_core_loc_conf t 结 构 体 ， 以 及 其 
loc_conf 成 员 指 同 的 所 有 HTTP 模 块 在 location L1 块 内 的 配置 项 与 server A 
块 结合 了 起 来 。 解 析 到 location L2 时 会 做 相同 处 理 ， 这 也 就 得 到 了 图 10- 
6。 
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属于 location L2 块 
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图 10-6 ”同一 个 servet 块 下 的 ngx_http_core_loc_conf t 是 通过 双向 链表 关 
联 起 来 的 


事实 上 ，location 之 间 是 可 以 租 套 的 ， 那 么 它们 之 间 的 关联 关系 又 


是 怎样 的 昵 ?扩展 一 下 10.1 市 中 的 例子 ， 即 假设 配置 文件 如 下 : 





http { 

mytest_num 1; 

server { 
server_name A; 
listen 8000; 
listen 80; 
mytest_num 2; 
location /Li1 { 

mytest_num 3; 


location /Li1/CL1 { 
} 





这 时 多 了 一 个 新 的 location 块 LICL1， 它 隶属 于 location L1。 此 时 ， 
每 个 location 块 对 应 的 ngx_http_core_loc_conf t 结 构 体 间 是 通过 如 图 10-7 
所 示 的 形式 组 织 起 来 的 。 









属于 server A 块 


soner A P ore ler mmf MET 


locations 
ngx_http_location_ queue_t 0 


ngx_http _core_loc_conf tt 
[1 


locations 





















属于 location Ll 块 








inclusive 


ngx_http _location_queue_t 
属于 location L1/CL1 块 


ngx_http _location_queue 1 















ngx_http _core _loc_conf tt 


















exact 
inclusive 





图 10-7 ”location 块 谱 套 后 ngx_http_cote_loc_conf t 结 构 体 间 的 关系 


可 以 看 到 ， 仍 然 是 通过 ngx_http_core_loc_conf t 结 构 体 中 的 locations 
站 针 来 容纳 属于 它 的 location 块 的 。 当 locations 为 空 指针 时 ， 表 示 当 前 的 
location 块 下 不 再 骨 套 location 块 ， 人 否则 表示 还 有 新 的 location 块 。 在 10.2.4 
节 的 合并 配置 项 的 代码 中 可 以 看 到 这 一 点 。 


10.2.4 不 同 级 别 配 置 项 的 合并 


考虑 到 HTTP 模 块 可 能 需要 合并 不 同 级 别 的 同名 配置 项 ， 因 此 ， 
HTTP 框 架 为 ngx_http_module_t 接 口 提 供 了 merge_srv_conf 方 法 ， 用 于 合 
并 main 级 别 与 srv 级 别 的 server 相 关 的 配置 项 ， 同 时 ， 它 还 提供 了 
merge_loc_conf 方 法 ， 用 于 合并 main 级 别 、srv 级 别 、loc 级 别 的 location 相 
关 的 配置 项 。 当 然 ， 如 果 不 存 在 合并 不 同 级 别 配 置 项 的 场景 ， 那 么 可 以 
不 实现 这 两 个 方法 。 下 面 仍然 以 10.1 节 的 配置 文件 为 例 ， 展 示 了 不 同 级 
别 的 配置 项 结构 体 是 如 何 合 并 的 ， 如 图 10-8 所 示 。 


本 本 本 本 本 本 本 本 解析 直属 于 http 块 下 的 main 配置 项 


NC 

http 块 Fecreate _main_conf 配置 项 指针 模块 5 用 create -main_eonf + 创建 的 结构 休 
el 0 el i ND 
======2 模块 5 用 create_srv _conf_t 创 建 的 结构 体 


http 块 Fcreate _srv_conf 配置 项 指针 
国医 面 本 国画 夯 夯 模块 5 用 create_loc_conf_t 创 建 的 结构 体 


http 块 create _ loc _conf 配置 项 指针 


| 





| 解析 http 块 下 serverA 的 配置 项 


server A 块 下 create _srv_conf 配 置 项 指针 模块 5 用 create_srv_conf 1 创建 的 结构 体 


Le eo ee 模块 5 用 create _loc _conf 1 创建 的 结构 体 


server A 块 下 create_loc _conf 配置 项 指针 


| 


路 





解析 http 块 下 server A 块 中 
location L 1 的 配置 项 






L 
location L 1 块 下 create_loc _conf 配置 项 指针 


图 10-8 main、stv、loc 级 别 的 同名 配置 项 合并 前 的 内 存 示意 图 


图 10-8 以 第 5 个 HTTP 模 块 〈 通 党 是 ngx_http_static_module 模 块 ) 为 
例 ， 展 示 了 在 解析 完 http 块 、server A 块 、location L1 块 后 是 如 何 合并 配 
置 项 的 。 第 5 个 HTTP 模 块 在 解析 这 3 个 配置 块 时 ，create_loc_conf t 方 法 
被 调用 了 3 次 ， 产 生 了 3 个 结构 体 ， 分 别 存 放 了 main、srv、loc 级 别 的 
location 相 关 的 配置 项 ， 这 时 可 以 合并 为 location L1 相 关 的 配置 结构 体 ; 


create_srv_conf {t 方 法 被 调用 了 两 次 ， 产 生 了 两 个 结构 体 ， 分 别 存 放 了 
main、srv 级 别 的 配置 项 ， 这 时 也 可 以 合并 为 server A 块 相关 的 配置 结构 
体 。 








合并 配置 项 可 能 不 太 容 易 理 解 ， 下 面 我 们 就 在 代码 实现 层面 上 再 做 
个 简要 的 介绍 ， 同 时 也 对 10.2.2 节 和 10.2.3 节 的 内 容 做 一 个 回顾 。 这 个 合 
并 操作 是 在 ngx_http_merge_servers 方 法 下 进行 的 ， 先 来 简单 地 看 看 它 是 
怎么 被 调用 的 : 








/A/*cmcf 是 


ngx_http_core_module 在 


http 块 下 的 全 局 配置 结构 体 ， 在 


Servers 成 员 ， 这 是 一 个 动态 数组 ， 它 保存 着 所 有 


ngx_http_core_srv_conf_t 的 指针 ， 从 而 关联 了 所 有 的 





Server 块 


*/ 
cmcf = ctx->main_conf[ngx_http_core module.ctx_ index]; 
// ngx_modules 数 组 中 包含 所 有 的 


Nginx 模 块 


for (m= 0; ngx_ modules[m]; m++) { 
// 遍历 所 有 的 


HTTP 模 块 


if (ngx_modules[m]->type != NGX_HTTP_MODULE) { 


continue; 


/* ngx_modules[m] 是 一 个 


ngx_module_t 模 块 结构 体 ， 它 的 


Ctx 成 员 对 于 


HTTP 模 块 来 说 是 


ngx_http_module_t 接 口 


*/ 
ngx_http_module t *module = ngx_modules[m]->ctx; 
// Ctx_index 是 这 个 


HTTP 模 块 在 所 有 


HTTP 模 块 中 的 序号 


mi = ngx_modules[m]->ctx_index; 
// 调用 


ngx_http_merge_servers 方 法 合并 


ngx_modules[m] 模 块 


rv = ngx_http_merge_servers(cf, cmcf, module, mi); 





ngx_http_merge_servers 方 法 不 只 是 合并 了 server 相 关 的 配置 项 ， 它 
同时 也 会 合并 location 相 关 的 配置 项 ， 下 面 再 来 看 看 它 的 实现 ， 代 码 如 
下 





static char * ngx_http_merge_ servers(ngx_conf_t *cf, ngx_http_core main conf_t 





char *rv; 
ngx_uint_t s; 


ngx_http_conf_ctx_t *ctx, saved; 
ngx_http_core_loc conf_t *clcf,; 
ngx_http_core_srv_conf_t **cscfp; 
/* 从 











ngx_http_core_main_conf_t 的 





Servers 动 态 数 组 中 可 以 获取 所 有 的 


ngx_http_core_srv_conf_t 结 构 体 





*/ 
cscfp = cmcf->servers.elts,; 
// 注意 ; 这 个 


CtX 是 在 


http{j} 块 下 的 全 局 


ngx_http_conf_ctx_t 结 构 体 





ctx = (ngx_http_conf_ctx t *) cf->ctx; 
saved = *ctx; 
// 遍历 所 有 的 





Server 块 下 对 应 的 


ngx_http_core_srv_conf_t 结 构 体 





for (s = 0; s < cmcf->servers.nelts,; s++) { 
/*Srv_conf 将 指向 所 有 的 


HTTP 模 块 产生 的 


Server 相 关 的 


Srv 级 别 配置 结构 体 


WA 
ctx->srv_conf = cscfp[s]->ctx->srv_conf; 
// 如 果 当 前 


HTTP 模 块 实现 了 


merge_srv_conf， 则 再 调用 合并 方法 


If (module->merge_ srv_conf) { 
/* 注 意 ， 在 这 里 合并 配置 项 时 ， 


saved.srv_conf[ctx_index] 参 数 是 当前 
HTTP 模 块 在 
http{} 块 下 由 
create_srv_conf 方 法 创建 的 结构 体 ， 而 
cscfp[s]j->ctx->srv_conf[ctx_index] 参数 则 是 在 
Server{} 块 下 由 
create_srv_conf 方 法 创建 的 结构 体 
*/ 
rv = module->merge_srv_conf(cf, saved,.srv_ conf[ctx_index], cscfp[s]-> ct 

// a 

HTTP 模 块 实现 了 


merge_srv_conf， 则 再 调用 合并 方法 


if (module->merge_ loc conf) { 
/*cscfp[s]->ctx->loc_conf 这 个 动态 数组 中 的 成 员 都 是 由 


server{} 块 下 所 有 
HTTP 模 块 的 
create_loc_conf 方 法 创建 的 结构 体 指针 


*/ 
ctx->loc_conf = cscfp[s]->ctx->loc_conf; 


/* 首 先 将 


http{} 块 下 


main 级 别 与 


Server{f} 块 下 


Srv 级 别 的 


location 相 关 的 结构 体 合 并 


SA 


rv = module->merge_loc conf(cf, 


/*clcf 是 


Server 块 下 


ngx_http_core_module 模 块 使 用 


Create_1oc_conf 方 法 产生 的 


ngx_http_core_1loc_conf 七 结构 体 ， 在 





10.2.3 节 中 曾经 说 过 ， 它 的 


locations 成 员 将 以 双向 链表 的 形式 关联 到 所 有 当前 


Server{} 块 下 的 


]Jocation 块 


4 


saved,.loc conf[ctx_index], cscfp[s]-> ct 


clcf = cscfp[s]->ctx->loc_conf[ngx_http_core_module.ctx_index]; 


/* 调 用 


ngx_http_merge_locations 方 法 ,将 


Server{} 块 与 其 所 包含 的 


location{} 块 下 的 结构 体 进行 合并 


4 
rv = 


ngx_http_merge_locations(cf, clcf->locations, 


cscfp[s]->ctx->loc_conf, 
module, ctx_index); 





ngx_http_merge_locations 方 法 负责 合并 location 相 关 的 配置 项 ， 上 面 
己 经 将 main 级 别 与 srv 级 别 做 过 合并 ， 接 下 来 再 次 将 srv 级 别 与 loc 级 别 做 
合并 。 每 个 server 块 ngx_http_core_loc_conf t 中 的 locations 双 问 链 表 会 包 
含 所 属 的 全 部 location 块 ， 遇 有 历 它 以 合并 srv、loc 级 别 配置 项 ， 如 下 所 


钞 。 








static char * 
ngx_http_merge_ locations(ngx_conf_t *cf, ngx_queue _t *]locations, 
void **]oc conf, ngx_http_module t *module, ngx_uint _t ctx_ index) 
{ 

char *ryv; 

ngx_queue _t *q; 

ngx_http_conf_ctx_t *ctx, saved; 

ngx_http_core_loc conf_t *clcf,; 

ngx_http_location_queue _t *1q; 

/* 如 果 








locations 链 表 为 空 ， 也 就 是 说 ， 当 前 


Server 块 下 没有 


Jocation 块 ， 则 立刻 返回 





*/ 
if (locations == NULL) { 
return NGX_CONF_OK,; 
} 
ctx = (ngx_http_conf_ctx_t *) cf->ctx; 
saved = *ctx; 
// 遍历 
]ocations 双 向 链表 
for (q = ngx_queue_ head(locations); 
q != ngx_queue_sentinel(locations); 


ngx_queue_next(q)) 


(ngx_http_location queue t *) 9q; 


10.2.3 节 中 曾经 讲 过 ， 如 果 


location 后 的 匹配 字符 囊 不 依靠 


Nginx 自 定义 的 通配符 就 可 以 完全 匹配 的 话 ， 则 


eXact 指 向 当前 


Jocation 对 应 的 


ngx_http_core_loc_conf_t 结 构 体 ， 否 则 使 用 





inclusive 指 向 该 结构 体 ， 且 


eXact 的 优先 级 高 于 


inclusive */ 
clcf = lq->exact 1q->exact : 1q->inclusive,; 
/*clcf->loc_conf 这 个 指针 数组 里 保存 着 当前 


location 下 所 有 


HTTP 模 块 使 用 


create_1oc_conf 方 法 生成 的 结构 体 的 指针 


*/ 
ctx->loc_conf = clcf->loc_conf; 
// 调用 


merge_loc_conf 方 法 合并 


Srv、 


loc 级 别 配 置 项 


rv = module->merge_loc conf(cf, loc_ conf[ctx_index], 
clcf->loc_ conf[ctx_index]); 





/* 注 意 ， 因 为 


location{} 中 可 以 继续 座 套 


location{} 配 置 块 ， 所 以 是 可 以 继续 合并 的 。 在 


10.1 节 的 例子 中 没有 


Location 谱 套 ， 


10.2.3 节 的 例子 是 体现 出 谋 套 关系 的 ， 可 以 对 照 着 图 


19-5 来 理解 


4 
rv = ngx_http_merge_locations(cf，clcf->1locations，CclLlcf->1oc_conf，module，( 


} 
*ctx = saved,; 
return NGX_CONF_OK,; 





在 针对 每 个 HTTP 模 块 循环 调用 ngx_http_merge_servers 方 法 后 ， 就 
可 以 完成 所 有 的 合并 配置 项 工作 了 。 





10.3 监听 端口 的 管理 


监听 问 口 属于 server 虚 拟 主机 ， 它 是 由 server{f} 块 下 的 listen 配 置 项 诀 
定 的 。 同 时 ， 它 与 server{} 块 对 应 的 ngx_http_core_srv_conf t 结 构 体 密切 
相关 ， 本 节 将 介绍 这 两 者 间 的 关系 ， 以 及 监听 端口 的 数据 结构 。 


每 监听 一 个 TCP 端 口 ， 都 将 使 用 一 个 独立 的 ngx_http_conf_ port {t 结 
构 体 来 表示 ， 如 下 所 示 。 





typedef struct { 
// socket 地 址 家 族 


ngx_int_t family; 
// 监听 端口 


in_port_t port; 
// 监听 的 端口 下 对 应 着 的 所 有 


ngx_http_conf_addr_t 地 址 





ngx_array_t addrs,; 
} ngx_http_conf_port_t; 








这 个 保存 着 监听 端口 的 ngx_http_conf_port_t 将 由 全 局 的 
ngx_http_core_main_conf t 结 构 体 保存 。 下 面 再 来 看 一 下 ports 容 器 ， 如 
下 所 未 。 








typedef struct { 


// 存放 着 该 


http{} 配 置 块 下 监听 的 所 有 


ngx_http_conf_port_t 端 口 





ngx_array_t *ports; 


} ngx_http_core_ main conf_t; 








在 前 面 的 代码 中 ，ngx_http_conf_port_t 的 addrs 动 态 数 组 可 能 不 太 容 
易 理 解 。 可 先 回 顾 一 下 listen 配 置 项 的 语法 ， 在 10.1 节 的 例子 中 ， 对 同一 
个 端口 8000， 我 们 可 以 同时 监听 127.0.0.1:8000、173.39.160.51:8000 这 两 
个 地 址 ， 当 一 台 物 理 机 器 具备 多 个 IP 地 址 时 这 是 很 有 用 的 。 具 体 到 
HTTP 框 架 的 实现 上 ，Nginx 是 使 用 ngx_http_conf_addr t 结 构 体 来 表示 一 
个 对 应 厦 具 体 地 址 的 监 昕 端口 的 ， 因 此 ， 一 个 ngx_http_conf_port_t 将 会 
对 应 多 个 ngx_http_conf_addr t， 而 ngx_http_conf addr t 就 是 以 动态 数组 
的 形式 保存 在 addrs 成 员 中 的 。 


下 面 再 来 看 看 ngx_http_conf_addr t 的 定义 ， 如 下 所 示 。 





typedef struct { 
// 监听 套 接 字 的 各 种 属性 


ngx_http_listen opt_t opt,; 
/+ 六 再 





3 个 散 列表 用 于 加 速 寻 找到 对 应 监听 端口 上 的 新 连接 ， 确 定 到 底 使 用 哪个 


Server{} 虚 拟 主机 下 的 配置 来 处 理 它 。 所 以 ， 散 列表 的 值 就 是 


ngx_http_core_srv_conf_t 结 构 体 的 地 址 





AN 
// 完全 匹配 


Server name 的 散 列表 


ngx_hash_t hash 
// 通配符 前 置 的 散 列表 


ngx_hash wildcard_t *wc_head ; 
// 通配符 后 置 的 散 列 表 


ngx_hash_wildcard t *wc_tail,; 
#if (NGX_PCRE) 
// 下 面 的 


regex 数 组 中 元 素 的 个 数 


ngx_uint_t nregex; 
/*regex 指 向 静态 数组 ， 其 数组 成 员 就 是 


ngx_http_server_name_t 结 构 体 ， 表 示 正 则 表达 式 及 其 匹配 的 





Server 人 虚拟 主机 


*/ 

ngx_http_server_name_t *regex; 
#endif 

// 该 监听 端口 下 对 应 的 默认 





Server 人 虚拟 主机 


ngx_http_core_ srv_conf_t *default_ server,; 
// Servers 动 态 数 组 中 的 成 员 将 指向 





ngx_http_core_srv_conf_t 结 构 体 





ngx_array_t servers; 


} ngx_http_conf_addr_t; 








在 上 面 的 servers 动 态 数 组 中 ， 保 存 的 数据 类 型 是 
ngx_http_core_srv_conf_t**， 简 单 来 说 ， 就 是 由 servers 数 组 把 监听 的 端 
口 与 server{} 虚 拟 主机 关联 起 来 了 。 图 10-9 展 示 了 10.1 节 的 例子 中 监听 端 
口 与 server{} 虚 拟 主机 间 在 内 存 中 的 关系 。 





ngx_http _conf_port tt 


+family 








ngx_http_core_main_conf_t 


server A 配置 块 下 的 


ngx_http _core _loc _conf tt 





server B 配置 块 下 的 


ngx_http _core _loc _conf _t 


图 10-9 ”监听 端口 与 setvef 人 虚拟 主机 间 的 关系 


下 面 来 解释 一 下 图 10-9。 整 个 http{} 块 下 共 监 昕 了 3 个 端口 ， 分 别 是 
80、8000、8080， 因 此 ，ngx_http_core_main_conf t 中 的 ports 动 态 数 组 
有 3 个 ngx_http_conf_port_ t 成 员 存放 这 3 个 端口 。 除 了 8000 端 口 对 应 了 两 
个 ngx_http_conf _ addr t 结 构 体 外 《分 别 是 127.0.0.1:8000 和 
173.39.160.51:8000) ，80 和 8080 都 相当 于 默认 监听 了 该 端口 下 的 所 有 地 
址 (实际 上 ，listen 80 就 相当 于 listen*.80) ， 因 此 ， 这 两 个 端口 各 自 对 
应 了 一 个 ngx_http_conf_addr t 结 构 体 。 每 个 监听 地 址 
ngx_http_conf addr t 的 servers 动 态 数组 中 关联 着 监听 地 址 对 应 的 server{} 
虚拟 主机 ， 根 据 10.1 节 的 例子 可 以 知道 ，server A 配 置 块 对 应 着 监听 地 址 
*.80 和 127.0.0.1:8000， 而 server B 配 置 块 对 应 着 监听 地 址 *.80、*.8080 和 
173.39.160.51:8000。 


对 于 每 一 个 监听 地 址 ngx_http_conf_addr t， 都 会 有 8.3.1 节 中 介绍 过 
的 ngx_listening_t 与 其 相对 应 ， 而 ngx_listening _t 的 handler 回 调 方法 设置 
为 ngx_http_init_connection， 所 以 ， 新 的 TCP 连 接 成 功 建立 后 都 会 调用 
ngx_http_init_connection 方 法 初始 化 HTTP 相 关 的 信息 ， 第 11 章 将 会 详细 


介绍 ngx_http_init_connection 方 法 的 实现 。 


10.4 ”server 的 快速 检索 


在 10.2.2 市 中 可 以 看 到 ， 每 一 个 虚拟 主机 server{} 配 置 块 都 由 一 个 
ngx_http_core_srv_conf t 结 构 体 来 标识 ， 这 些 ngx_http_core_srv_conf_t 义 
通过 全 局 的 ngx_http_core_main_conf t 结 构 中 的 servers 动 态 数组 关联 起 
来 的 。 这 意味 着 当 开 始 处 理 一 个 HITP 新 连接 时 ， 接 收 到 HITP 头 部 并 取 
到 Host 后 ， 需 要 遍历 ngx_http_core_main_conf t 的 servers 数 组 才能 找到 与 
server name 配 置 项 匹配 的 虚拟 主机 配置 块 ， 这 样 的 时 间 复 杂 度 显然 是 不 
可 接受 的 ， 因 为 当 nginx.conf 配 置 文件 中 拥有 数 以 百 计 的 server{} 块 时 ， 
查询 效率 就 太 低 了 。 于 是 ，HTTP 框 架 使 用 了 第 7 章 中 介绍 过 的 散 列 表 来 
存放 虚拟 主机 ， 其 中 每 个 元 素 的 关键 字 是 server name 字 符 串 ， 而 值 则 是 
ngx_http_core_srv_conf t 结 构 体 的 指针 。 





在 10.3 节 中 介绍 过 ， 负 责 监 听 一 个 端口 地 址 的 ngx_http_conf_ addr { 
结构 体 拥有 下 面 3 个 成 员 hash、wc_head、wc_tail， 这 3 个 成 员 对 应 着 
7.7.3 节 中 介绍 过 的 带 通 配 符 的 散 列表 。 这 个 带 通 配 符 的 散 列 表 的 使 用 方 

法 〈 包 括 如 何 构造 、 检 索 ) 在 7.7 节 中 已 详细 描述 过 ， 这 里 不 再 更 述 








10.5 location 的 快速 检索 





从 10.2.3 节 中 可 以 了 解 到 ， 每 一 个 server 块 可 以 对 应 着 多 个 location 
块 ， 而 一 个 location 块 还 可 以 继续 骨 套 多 个 location 块 。 每 一 批 location 块 
是 通过 双向 链表 与 它 的 父 配置 块 〈 要 么 属于 server 块 ， 要 么 属于 location 
块 ) 关联 起 来 的 。 由 双向 链表 的 查询 效率 可 以 知道 ， 当 一 个 请 求 根 据 
10.4 节 中 描述 过 的 散 列 表 快 速 查询 到 server 块 时 ， 必 须 遍 历 其 下 的 所 有 
location 组 成 的 双向 链表 才能 找到 与 其 URI 匹 配 的 location 配 置 块 ， 这 也 是 
用 户 无 法 接受 的 。 下 面 看 看 HTTP 框 架 又 是 怎样 通过 静态 的 二 又 查找 树 
来 保存 location 的 。 

















// cmcf 就 是 该 


http 块 下 全 局 的 





ngx_http_core_main_conf_t 结 构 体 


cmcf = ctx->main_conf[ngx_http_core module.ctx_ index]; 
/*CSCfp 指 向 保存 所 有 


ngx_http_core_srv_conf_t 结 构 体 指针 的 





Servers 动 态 数组 的 第 


1 个 元 素 


YA 
cscfp = cmcf->servers.elts,; 
// 遍历 


http 块 下 的 所 有 


Server 块 


for (s = 0; s < cmcf->servers.nelts; s++) { 
/A/*Cclcf 是 


Server 块 下 的 


ngx_http_core_loc_conf_t 结 构 体 ， 





1ocations 成 员 以 双向 链表 关联 着 隶属 于 这 个 


Server 块 的 所 有 


location 块 对 应 的 


ngx_http_core_loc_conf_t 结 构 体 





* 

/ 

clcf = cscfp[s]->ctx->loc_conf[ngx_http_core_ module.ctx_index]; 
/将 


ngx_http_core_loc_conf_t 组 成 的 双向 链表 按照 





location 匹 配 字 符 串 进行 排序 。 注 意 : 这 个 操作 是 递归 进行 的 ， 如 果 某 个 
location 块 下 还 具有 其 他 

]Jocation， 那么 它 的 

locations 链 表 也 会 被 排序 


Wy 
If (ngx_http_init_ locations(cf, cscfp[s], clcf) != NGX_OK) { 
return NGX_CONF_ERROR, 


} 
/* 根 据 已 经 按照 


location 字 符 串 排序 过 的 双向 链表 ， 快 速 地 构建 静态 的 二 又 查找 树 。 与 


ngx_http_init_locations 方 法 类 似 ， 这 个 操作 也 是 递归 进行 的 


*/ 
If (ngx_http_init_static location trees(cf, clcf) != NGX_OK) { 
return NGX_CONF_ERROR, 





} 
} 





注意 ， 这 里 的 二 又 碍 找 树 并 不 是 第 7 章 中 介绍 过 的 红 黑 树 ， 不 过 ， 
为 什么 不 使 用 红 黑 树 呢 ? 因为 location 是 由 nginx.conf 中 读 取 到 的 ， 它 是 
静态 不 变 的 ， 不 存在 运行 过 程 中 在 树 中 添加 或 者 删除 location 的 场景 ， 
而 且 红 黑 树 的 碍 询 效率 也 没有 重新 构造 的 静态 的 完全 平衡 二 又 树 高 。 





这 棵 静态 的 二 又 平衡 查找 树 是 用 ngx_http_location_tree_node_t 结 构 
体 来 表示 的 ， 如 下 所 示 。 





typedef struct ngx_http_location tree node s ngx_http_ location tree node t; 
struct ngx_http_location tree node s { 
// 左 子 树 





ngx_http_Jlocation tree_node t *]eft 
// 右 子 树 


ngx_http_Jlocation tree_node t *right; 
// 无 法 完全 匹配 的 


location 组 成 的 树 


ngx_http_location_ tree node t *tree; 
/* 如 果 


]ocation 对 应 的 


URI 匹 配 字 符 串 属于 能 够 完全 匹配 的 类 型 ， 则 


eXact 指 向 其 对 应 的 


ngx_http_core_loc_conf_t 结 构 体 ， 否 则 为 





NULL 空 指针 


4 





ngx_http_core_loc conf_t *exact; 
/* 如 果 


location 对 应 的 


URI 匹 配 字符 串 属于 无 法 完全 匹配 的 类 型 ， 则 


jnclusive 指 向 其 对 应 的 


ngx_http_core_loc_conf_t 结 构 体 ， 否 则 为 





NULL 空 指针 


4 





ngx_http_core_ loc conf_t *inclusive,; 
// 自动 重 定向 标志 


u_char auto_redirect; 
// name 字 符 串 的 实际 长 度 


u_char len; 
// name 指 向 


]ocation 对 应 的 


URI 匹 配 表 达 式 


u_char name[1]; 


}; 





HTTP 框 架 在 ngx_http_core_module 模 块 中 定义 了 


ngx_http_core_find_location 方 法 ， 用 于 从 静态 二 叉 查 找 树 中 快速 检索 到 
ngx_http_core_loc_conf t 结 构 体 ， 这 在 第 11 章 探讨 HTTP 请 求 的 处 理 过 程 
时 将 会 碰 到 。 


10.6_ HTTP 请 求 的 11 个 处 理 阶 段 


Nginx 为 什么 要 把 HTTP 请 求 的 处 理 过 程 分 为 多 个 阶段 呢 ? 这 要 从 第 
8 章 介 绍 过 的 “一 切 锅 模块 ”说 起 。Nginx 的 模块 化 设计 使 得 每 一 个 HTTP 
模块 可 以 仅 专注 于 完成 一 个 独立 的 、 简 单 的 功能 ， 而 一 个 请 求 的 完整 处 
理 过 程 可 以 由 无 数 个 HTTP 模块 共同 合作 完成 。 这 种 设计 有 非常 好 的 简 
单 性 、 可 测试 性 、 可 扩展 性 ， 然 而 ， 当 多 个 HTTP 模 块 流水 式 地 处 理 同 
一 个 请 求 时 ， 单 一 的 处 理 顺 序 是 无 法 满足 灵活 性 需求 的 ， 每 一 个 正在 处 
理 请 求 的 HTTP 模 块 很 难 灵活 、 有 效 地 指定 下 一 个 HTTP 人 处 理 模块 是 哪 一 
个 。 而 且 ， 不 划分 处 理 阶 段 也 会 让 HTTP 请 求 的 完整 处 理 流程 难以 管 
理 ， 每 一 个 HTTP 模 块 也 很 难 正确 地 将 自己 插入 到 完整 流程 中 的 合适 位 
置 中 。 


因此 ，HTTP 框 架 依据 常见 的 处 理 流程 将 处 理 阶段 划分 为 11 个 阶 
段 ， 其 中 每 个 处 理 阶段 都 可 以 由 任意 多 个 HITP 模 块 流水 式 地 处 理 请 
求 。 先 来 回顾 一 下 第 3 章 中 曾经 提 到 过 的 ngx_http_phases 阶 段 的 定义 ， 
如 下 所 示 。 





typedef enum { 
// 在 接收 到 完整 的 


HTTP 头 部 后 处 理 的 


HTTP 阶 段 


NGX_HTTP_POST_READ_PHASE = 9， 
/* 在 将 请 求 的 





URI 与 


location 表 达 式 匹配 前 ， 修 改 请 求 的 


URI (所 谓 的 重 定向 ) 是 一 个 独立 的 


HTTP 阶 段 


#7 
NGX_HTTP_SERVER_REWRITE_PHASE， 
/* 根 据 请 求 的 


URI 寻 找 匹 配 的 


Jocation 表 达 式 ， 这 个 阶段 只 能 由 


ngx_http_core_module 模 块 实现 ， 不 建议 其 他 


HTTP 模 块 重新 定义 这 一 阶段 的 行为 





*/ 
NGX_HTTP_FIND_CONFIG_PHASE, 
/* 在 





NGX_HTTP_FIND_CONFIG_PHASE 阶 段 寻 找到 匹配 的 





location 之 后 再 修改 请 求 的 


URI*/ 
NGX_HTTP_REWRITE_PHASE， 
/* 这 一 阶段 是 用 于 在 


rewrite 重 写 


URL 后 ， 防 止 错误 的 


nginx.conf 配 置 导致 死 循 环 ( 递 归 地 修改 


URI) ， 因 此 ， 这 一 阶段 仅 由 





ngx_http_core_module 模 块 处 理 。 目 前 ， 控 制 死 循环 的 方式 很 简单 ， 首 先 检查 


rewrite 的 次 数 ， 如 果 一 个 请 求 超过 


10 次 重 定向 


/ 就 认为 进入 了 


rewrite 死 循环 ， 这 时 在 


NGX_HTTP_POST_REWRITE_PHASE 阶 段 就 会 向 用 户 返回 


500， 表 示 服 务 器 内 部 错误 


*/ 
NGX_HTTP_POST_REWRITE_PHASE, 
/* 表 示 在 处 理 


NGX_HTTP_ACCESS_PHASE 阶 段 决 定 请 求 的 访问 权限 前 ， 


HTTP 模 块 可 以 介入 的 处 理 阶 段 


*/ 
NGX_HTTP_PREACCESS_PHASE, 
// 这 个 阶段 用 于 让 


HTTP 模 块 判断 是 否 允 许 这 个 请 求 访问 


Nginx 服 务 器 


NGX_HTTP_ACCESS_PHASE, 
/* 在 


NGX_HTTP_ACCESS_PHASE 阶 段 中 ， 当 


HTTP 模 块 的 


handler 处 理 函 数 返 回 不 允许 访问 的 错误 码 时 (实际 就 是 


NGX_HTTP_FORBIDDEN 或 者 


NGX_HTTP_UNAUTHORIZED) ， 这 里 将 负责 向 用 户 发 送 拒绝 服务 的 错误 响应 。 因 此 ， 这 个 阶段 实际 上 用 于 给 


NGX_HTTP_ACCESS_PHASE 阶 段 收尾 


A 
NGX_HTTP_POST_ACCESS_PHASE, 
/* 这 个 阶段 完全 是 为 





try_files 配 置 项 而 设立 的 ， 当 


HTTP 请 求 访问 静态 文件 资源 时 ， 


try_files 配 置 项 可 以 使 这 个 请 求 顺序 地 访问 多 个 静态 文件 资源 ， 如 果 某 一 次 访问 失败 ， 则 继续 访问 


try_files 中 指定 的 下 一 个 静态 资源 。 这 个 功能 完全 是 在 





NGX_HTTP_TRY_FILES_PHASE 阶 段 中 实现 的 


六 4 
NGX_HTTP_TRY_FILES_PHASE, 
// 用 于 处 理 





HTTP 请 求 内 容 的 阶段 ， 这 是 大 部 分 


HTTP 模 块 最 愿意 介入 的 阶段 


NGX_HTTP_CONTENT_PHASE， 
/* 处 理 完 请 求 后 记录 日 志 的 阶段 。 例 如 ， 


ngx_http_log_module 模 块 就 在 这 个 阶段 中 加 入 了 一 个 


handler 处 理 方 法 ， 使 得 每 个 


HTTP 请 求 处 理 完 毕 后 会 记录 


access_1og 访 问 日 志 


*/ 
NGX_HTTP_LOG_PHASE 
} ngx_http_phases ; 


as 


对 于 这 11 个 处 理 阶 段 ， 有 些 阶 段 是 必 备 的 ， 有 些 阶 段 是 可 选 的 ， 当 
然 也 可 以 有 多 个 HTTP 模 块 同时 介入 同一 阶段 (这 时 ， 将 会 在 一 个 阶段 
中 按照 这 些 HTTP 模 块 的 ctx_index 顺 序 来 依次 执行 它们 提供 的 handler 处 
理 方法 ) 。 在 10.6.1 节 中 将 会 介绍 这 11 个 阶段 共同 适用 的 规则 ， 在 10.6.2 
节 ~10.6.12 节 则 会 描述 这 些 具体 的 处 理 阶 段 。 


@ 注意 ”ngx_http_phases 定 义 的 11 个 阶段 是 有 顺序 的 ， 必 须 按 照 
其 定义 的 顺序 执行 。 同 时 也 要 意识 到 ， 并 不 是 说 一 个 用 户 请 求 最 多 只 能 
经 过 11 个 HTTP 模 块 提 供 的 ngx_http_handler_pt 方 法 来 处 理 ， 
NGX_HTTP_POST_READ_PHASE. 
NGX_HTTIP_SERVER_REWRITE_PHASE. 
NGX_HTTIP_REWRITE_PHASE NGX_HTIP_ PREACCESS_PHASE. 


NGX_HTIP_ACCESS_ PHASE NGX_ HTTP_ CONTENT_ PHASE. 








NGX_HTTP_LOG_PHASE 这 7 个 阶段 可 以 包括 任意 多 个 处 理 方 法 ， 它 们 
是 可 以 同时 作用 于 同一 个 用 户 请 求 的。 而 
NGX_HTTP_FIND_CONFIG_PHASE.、 
NGX_HTTP_POST_REWRITE_PHASE. 


NGX_HTIP_POST_ACCESS_PHASE. 








NGX_HTTP_TRY_FILES_PHASE 这 4 个 阶段 则 不 允许 HTTP 模 块 加 入 自 


己 的 ngx_http_handler_pt 方 法 处 理 用 户 请 求 ， 它 们 仅 由 HTTP 框 架 实现 。 


10.6.1 HTTP 处 理 阶段 的 普 适 规则 


下 面 先 来 看 看 HTTP 阶 段 的 定义 ， 它 包括 checker 检 查 方法 和 handler 
处 理 方 法 ， 如 下 所 示 。 





typedef struct ngx_http_phase handler_s ngx_http_phase_ handler_t; 
人 





HTTP 处 理 阶段 中 的 


Checker 检 查 方法 ， 仅 可 以 由 


HTTP 框 架 实 现 ， 以 此 控制 


HTTP 请 求 的 处 理 流程 


*/ 
typedef ngx_int_t (*ngx_http_phase_ handler_pt) (ngx_http_request t *r, ngx_http_pha: 
/* 由 


HTTP 模 块 实现 的 


handler 处 理 方 法 ， 这 个 方法 在 第 


ngx_http_mytest_handler 方 法 实现 过 


A 
typedef ngx_int_t (*ngx_http_handler_pt)(ngx_http_request t *r); 
// 注意 : 


ngx_http_phase_handler_t 结 构 体 仅 表示 处 理 阶段 中 的 一 个 处 理 方 法 


struct ngx_http_phase handler _s { 
/在 处 理 到 某 一 个 


HTTP 阶 段 时 ， 


HTTP 框 架 将 会 在 


checker 方 法 已 实现 的 前 提 下 首先 调用 


Checker 方 法 来 处 理 请 求 ， 而 不 会 直接 调用 任何 阶段 中 的 


handler 方 法 ， 只 有 在 


checker 方 法 中 才 会 去 调用 





handler 方 法 。 因 此 ， 事 实 上 所 有 的 


checker 方 法 都 是 由 框架 中 的 


ngx_http_core_module 模 块 实现 的 ， 且 普通 的 


HTTP 模 块 无 法 重 定义 





checker 方 法 


* 
/ 
ngx_http_phase_ handler_ pt checker; 
/* 除 


ngx_http_core_module 模 块 以 外 的 


HTTP 模 块 ， 只 能 通过 定义 


handler 方 法 才能 介入 某 一 个 


HTTP 处 理 阶 段 以 处 理 请 求 


4 
ngx_http_handler_pt handler; 
// 将 要 执行 的 下 一 个 


HTTP 处 理 阶段 的 序号 


/* next 的 设计 使 得 处 理 阶 段 不 必 按 顺序 依次 执行 ， 既 可 以 向 后 跳跃 数 个 阶段 继续 执行 ， 也 可 以 跳跃 到 之 前 


next 表 示 下 一 个 处 理 阶段 中 的 第 


二 人 


ngx_http_phase_handler_t 处 理 方法 


4 
ngx_uint_t next; 


. 





@ 注意 ”通常 ， 在 任意 一 个 ngx_http_phases 阶 段 ， 都 可 以 拥有 零 
个 或 多 个 ngx_http_phase_handler_t 结 构 体 ， 其 含义 更 接近 于 某 个 HTTP 模 


块 的 处 理 方法 。 


一 个 http{} 块 解析 完毕 后 将 会 根据 nginx.conf 中 的 配置 产生 由 
ngx_http_phase_handler t 组 成 的 数组 ， 在 处 理 HTTP 请 求 时 ， 一 般 情况 下 
这 些 阶段 是 顺序 向 后 执行 的 ， 但 ngx_http_phase_handler_t 中 的 next 成 员 
使 得 它们 也 可 以 非 顺 序 执行 。ngx_http_phase_engine_t 结 构 体 就 是 所 有 
ngx_http_phase_handler t 组 成 的 数组 ， 如 下 所 示 。 








typedef struct { 
/*handlers 是 由 


ngx_http_phase_handler_t 构 成 的 数组 首 地 址 ， 它 表示 一 个 请 求 可 能 经 历 的 所 有 
ngx_http_handler_pt 处 理 方法 


4 
ngx_http_phase_handler t *handlers,; 
/* 表 示 


NGX_HTTP_SERVER_REWRITE_PHASE 阶 段 第 
1 个 
ngx_http_phase_handler_t 处 理 方法 在 


handlers 数 组 中 的 序号 ， 用 于 在 执行 


HTTP 请 求 的 任何 阶段 中 快速 跳 转 到 


NGX_HTTP_SERVER_REWRITE_PHASE 阶 段 处 理 请 求 


*/ 
ngx_uint_t server_rewrite index; 
/* 表 示 


NGX_HTTP_REWRITE_PHASE 阶 段 第 


1 个 


ngx_http_phase_handler_t 处 理 方法 在 


handlers 数 组 中 的 序号 ， 用 于 在 执行 


HTTP 请 求 的 任何 阶段 中 快速 跳 转 到 


NGX_HTTP_REWRITE_PHASE 阶 段 处 理 请 求 


4 
ngx_uint_t location rewrite_ index; 
} ngx_http_phase_engine_t; 








可 以 看 到 ，ngx_http_phase_engine t 中 保存 了 在 当前 nginx.conf 配 置 
下 ， 一 个 用 户 请 求 可 能 经 历 的 所 有 ngx_http_handler_pt 处 理 方法 ， 这 是 
所 有 HTTP 模 块 可 以 合作 处 理 用 户 请 求 的 关键 ! 这 个 
ngx_http_phase_engine_t 结 构 体 是 保存 在 全 局 的 
ngx_http_core_main_conf t 结 构 体 中 的 ， 如 下 所 示 。 








typedef struct { 
/* 由 下 面 各 阶段 处 理 方法 构成 的 


phases 数 组 构建 的 阶段 引擎 才 是 流水 式 处 理 


HTTP 请 求 的 实际 数据 结构 


*/ 
ngx_http_phase_engine_t phase_engine; 
/用 于 在 





HTTP 框 架 初 始 化 时 帮助 各 个 

HTTP 模 块 在 任意 阶段 中 添加 
HTTP 处 理 方法 ， 它 是 一 个 有 

11 个 成 员 的 
ngx_http_phase_t 数 组 ， 其 中 每 一 个 
ngx_http_phase_t 结 构 体 对 应 一 个 
HTTP 阶 段 。 在 
HTTP 框 架 初 始 化 完毕 后 ， 运 行 过 程 中 的 
phases 数 组 是 无 用 的 

*/ 


ngx_http_phase_t phases[NGX_HTTP_LOG_ PHASE + 11]; 


} ngx_http_core _ main conf_t; 








在 ngx_http_core_main_conf t 中 关于 HTTP 阶 段 有 两 个 成 员 
phase_engine 和 phases， 其 中 phase_engine 控 制 运行 过 程 中 一 个 HTTP 请 求 
所 要 经 过 的 HTTP 处 理 阶段 ， 它 将 配合 ngx_http_request_t 结 构 体 中 的 
phase_handler 成 员 使 用 (phase_handler 指 定 了 当前 请 求 应 当 执 行 哪 一 个 
HTTP 阶 段 〉; 而 phases 数 组 更 像 一 个 临时 变量 ， 它 实际 上 仪 会 在 Nginx 
局 动 过 程 中 用 到 ， 它 的 唯一 使 命 是 按照 11 个 阶段 的 概念 初始 化 








phase_engine 中 的 handlers 数 组 。 下 面 看 一 下 ngx_http_phase_t 的 定义 。 





typedef struct 
// handlers 动 态 数组 保存 着 每 一 个 


HTTP 模 块 初始 化 时 添加 到 当前 阶段 的 处 理 方 法 


ngx_array_t handlers; 
} ngx_http_phase_t; 





在 HTTP 框 染 的 初始 化 过 程 中 ， 任 何 HTTP 模 块 都 可 以 在 
ngx_http_module_t 接 口 的 postconfiguration 方 法 中 将 自 定义 的 方法 添加 到 
handler 动 态 数组 中 ， 这 样 ， 这 个 方法 就 会 最 终 添加 到 phase_engine 中 

(注意 ， 第 3 章 J 把 ngx_http_mytest_handler 方 法 加 入 

到 phases 的 handlers 数 组 中 ， 这 是 因为 对 于 
NGX_HTTP_CONTENT_PHASE 阶 段 来 襄 ， 还 有 男 一 种 初始 化 方法 ， 在 
10.6.11 节 中 我 们 会 介绍 ) 。 在 第 11 章 中 可 以 看 到 这 些 HITP 阶 段 是 如 何 











下 面 将 会 简要 介绍 这 11 个 HITP 处 理 阶段 ， 读 者 关注 重点 是 每 个 阶 
段 的 checker 方 法 都 做 了 些 什 么 。 


10.6.2 NGX HTTP POST _ READ _ PHASE 阶段 


当 HTTP 框 架 在 建立 的 TCP 连 接 上 接收 到 客户 发 送 的 完整 HTTP 请 求 
头 部 时 ， 开 始 执行 NGX_HTTP POST_ READ_ PHASE 阶段 的 checker 方 


» 


法 。 下 面 先 来 看 看 它 的 checker 方 法 ngx_http_core_generic_phase， 这 是 一 
个 很 典型 的 checker 方 法 ， 下 面 就 给 出 相关 代码 ， 以 便 读 者 对 checker 方 
法 的 执行 过 程 有 个 直观 认识 。 








ngx_int_t ngx_http_core_generic_phase(ngx_http_request_t *r，ngx_http_phase_handJer - 


// 调用 这 一 阶段 中 各 
HTTP 模 块 添加 的 


handler 处 理 方法 


ngx_int t rc = ph->handler(r); 
/* 如 果 


handler 方 法 返回 
NGX_OK， 之 后 将 进入 下 一 个 阶段 处 理 ， 而 不 会 理会 当前 阶段 中 是 否 还 有 其 他 的 处 理 方法 


*/ 
If (rc == NGX_OK) { 
r->phase_handler = ph->next; 
return NGX_AGAIN,; 


} 
/* 如 果 
handler 方 法 返回 
NGX_DECLINED， 那 么 将 进入 下 一 个 处 理 方法 ， 这 个 处 理 方法 既 可 能 属于 当前 阶段 ， 也 可 能 属于 下 一 个 阶段 。 注 意 
NGX_OK 与 
NGX_DECLINED 之 间 的 区 别 


*/ 
if (rc == NGX_DECLINED) { 
r->phase_handler++; 
return NGX_AGAIN,; 


} 
/* 如 果 


handler 方 法 返回 
NGX_AGAIN 或 者 
NGX_DONE， 那 么 当前 请 求 将 仍然 停留 在 这 一 个 处 理 阶 段 中 


*/ 
if (rc == NGX_AGAIN || rc == NGX_DONE) { 
return NGX_OK; 


} 
/* 如 果 
handler 方 法 返回 
NGX_ERROR 或 者 类 似 
NGX_HTTP_ 开 头 的 返回 码 ， 则 调用 
ngx_http_finalize _ request 结束 请 求 


*/ 
ngx_http_finalize_request(r, rc); 
return NGX_OK， 

} 





任意 HTTP 模块 需要 在 NGX_HTTP_POST_READ_PHASE 阶 段 处 理 
HTTP 请 求 时 ， 必 须 首 先 在 ngx_http_core_main_conf_t 结 构 体 中 的 
phases[INGX_HTTP_POST_READ_PHASE] 动 态 数 组 中 添加 自己 实现 的 
ngx_http_handler_pt 方 法 。 在 此 阶段 中 ，ngx_http_handler_pt 方 法 的 返回 
值 可 以 产生 4 种 不 同 的 影响 ， 总 结 见 表 10-1。 


表 10-1 NGX_HTTIP POST _ READ _PHASE、 
NGX_HTTP PREACCESS_PHASE、NGX_HTTIP LOG_PHASE 阶 段 下 


HTTP 模 块 的 ngx_http_handler_pt 方 法 返回 值 意义 


返回 值 
执行 下 一 个 ngx_http phases 阶段 中 的 第 一 个 ngx_http_ handler pt 处 理 方法 。 这 意味 着 两 
点 : 中 即使 当前 阶段 中 后 续 还 有 一 些 HITP 模块 设置 了 ngx_http_handler_ pt 处 理 方法 ， 返 回 





NGX OK bie bee ee Rh 
二 NGX_OK 之 后 它们 也 是 得 不 到 执行 机 会 的 ; 四 如 果 下 一 个 ngx_http_phases 阶段 中 没有 任何 
HTTP 模块 设置 了 ngx_http_ handler_pt 处 理 方法 ， 将 再 次 寻找 之 后 的 阶段 ， 如 此 循环 下 去 
( 续 ) 
返回 值 总 “区 


按照 顺序 执行 下 一 个 ngx_http_handler pt 处 理 方法 。 这 个 顺序 就 是 ngx_http phase _ 

engine t 中 所 有 ngx_http_ phase handler t 结构 体 组 成 的 数组 的 顺序 
NGX AGAIN 当前 的 ngx_http_handler_pt 处 理 方 法 尚未 结束 ， 这 意味 着 该 处 理 方法 在 当前 阶段 有 机 会 再 
次 被 调用 。 这 时 一 般 会 把 控制 权 交 还 给 事件 模块 ， 当 下 次 可 写 事 件 发 生 时 会 再 次 执行 到 该 


NGX DECLINED 





NGX DONE i S 

3 ngx_http_handler_pt 处 理 方法 
NGX ERROR i Pe 
本 他 需要 调用 ngx_http_finalize_request 结束 请 求 
其 他 


目前 ， 官 方 的 ngx_http_realip_module 模 块 是 从 
NGX_HTTP_POST_READ_PHASE 阶 段 介入 以 处 理 HTTP 请 求 的 ， 它 在 
postconfiguration 方 法 中 是 这 样 将 自 定义 的 ngx_http_handler_pt 处 理 方 法 
添加 到 HTTP 框 架 中 的 ， 如 下 所 示 。 





// 这 个 


ngx_http_realip_init 方 法 实际 上 就 是 


postconfiguration 接 口 的 实现 


static ngx_int_t ngx_http_realip_ init(ngx_conf_t *cf) 


‘ 





ngx_http_handler_pt *h， 
// 首先 获取 到 全 局 的 


ngx_http_core_main_conf_t 结 构 体 





ngx_http_core main conf_t *cmcf = ngx_http_conf_get module main conf( cf, ngx_ht 
/*phases 数 组 中 有 








11 个 成 员 ， 取 出 


NGX_HTTP_POST_READ_PHASE 阶 段 的 





handlers 动 态 数 组 ， 向 其 中 添加 


ngx_http_handler_pt 处 理 方 法 ， 这 样 


ngx_http_realip_module 模 块 就 介入 


HTTP 请 求 的 


NGX_HTTP_POST_READ_PHASE 处 理 阶段 了 





yA 
h = ngx_array_push(&cmcf->phases[NGX_HTTP_POST_READ_PHASE] .handlers); 
if (h == NULL) { 
return NGX_ERROR,; 





/* ngx_http_realip_handler 方 法 就 是 实现 了 
ngx_http_handler_pt 接 口 的 方法 


*/ 
*h = ngx_http_realip_handler; 
/* 实 际 上 ， 同 一 个 


HTTP 模 块 的 同一 个 

ngx_http_realip_handler 方 法 ， 完 全 可 以 设置 到 两 个 不 同 的 阶段 中 的 。 例 如 ， 
phases[NGX_HTTP_PREACCESS_PHASE .handlers] 动 态 数 组 中 也 添加 了 
ngx_http_realip_hand1ler 方 法 


*/ 
h = ngx_array_push(&cmcf->phases[NGX_HTTP_PREACCESS_ PHASE] .handlers); 
if (h == NULL) { 
return NGX_ERROR,; 
} 


/*ngx_http_realip_handler 处 理 方法 同时 介入 了 


NGX_HTTP_POST_READ_PHASE、 





NGX_HTTP_PREACCESS_PHASE 这 两 个 


HTTP 处 理 阶 段 


*h = ngx_http_realip_handler; 
return NGX_OK， 
} 





通过 这 个 例子 可 以 看 到 怎样 在 NGX_HTTP POST READ PHASE 或 
者 NGX_HTTP PREACCESS PHASE 阶段 添加 HTTP 模 块 。 


10.6.3 NGX_HTTP_SERVER_REWRITE_PHASE 阶 段 


NGX_HTTP_SERVER_REWRITE_PHASE 阶 段 的 checker 方 法 是 
ngx_http_core_rewrite_phase。 表 10-2 总 结 了 该 阶段 Fngx_http_handler_pt 
处 理 方法 的 返回 值 是 如 何 影响 HTTP 框 架 执行 的 ， 注 意 ， 这 个 阶段 中 不 
存在 返回 值 可 以 使 请 求 直 接 跳 到 下 一 个 阶段 执行 。 


表 10-2 NGX_HTTIP SERVER_REWRTITE _ PHASE、 
NGX_HTTIP_REWRITE _ PHASE 阶段 下 HTTP 模 块 的 ngx_http_handler_bpt 
方法 返回 值 意义 

返回 值 意 义 
当前 的 ngx_http_handler_pt 处 理 方法 尚未 结束 ， 这 意味 着 该 处 理 方法 在 当前 阶段 中 有 机 会 


再 次 被 调用 
当前 ngx_http_ handler pt 处 理 方法 执行 完毕 ， 按 照 顺 序 执行 下 一 个 ngx_http_handler_pt 处 


省 


NGX DONE 


NGX DECLINED 


理 方法 
NGX AGAIN 
NGX DONE ea es PS 
二 需要 调用 ngx_http_finalize request 结束 请 求 
NGX ERROR 


其 他 


官方 提供 的 ngx_http_rewrite_module 模 块 定义 了 
ngx_http_rewrite_handler 方 法 ， 同 时 将 它 添加 到 了 
NGX_HTTP_SERVER_REWRITE_PHASE 和 


NGX_HTTP_ REWRITE_ PHASE 阶 段 ， 这 里 就 不 再 列举 其 代码 了 。 


10.6.4 NGX HTTP FIND_ CONFIG _ PHASE 阶段 


NGX_HTTP_FIND_CONFIG_PHASE 是 一 个 关键 阶段 ， 这 个 阶段 是 
不 可 以 跳 过 的 ， 也 就 是 说 ， 在 ngx_http_phase_engine_t 中 ， 处 理 方法 组 
成 的 数组 必然 要 有 阶段 的 处 理 方法 ， 因 为 这 是 HITP 框 架 基 于 location 设 
计 的 基石 。 


HTTP 框 架 提供 了 ngx_http_core_find_config_phase 方 法 用 于 执行 这 
一 步 又 ， 也 就 是 说 ， 任 何 HTTP 模 块 不 可 以 辣 这 一 阶段 中 添加 处 理 方法 
(添加 了 也 是 无 效 的 ) Ingx_http_core_find_config_phase 方 法 实际 上 就 是 
根据 NGX_HTTP_SERVER_REWRITE_PHASE 步 又 重 写 后 的 URI 检 索 出 
匹配 的 location 块 的 ， 其 原理 为 从 location 组 成 的 静态 二 又 查找 树 中 快速 
检索 ， 有 具体 可 参照 10.5 节 。 


10.6.5 NGX HTTP REWRITE PHASE 阶 段 


NGX_HTTP _ FIND_CONFIG_PHASE 阶 段 检 索 到 location 后 有 机 会 再 


次 利用 rewrite ( 重 写 ) URL， 这 一 工作 就 是 在 
NGX HTTP _ REWRITE _PHASE 阶 段 完成 的 。 


NGX_HTTP_REWRITE_PHASE 阶 段 与 10.6.3 节 中 的 
NGX_HTTP_SERVER_REWRITE_PHASE 阶 段 几 乎 是 完全 相同 的 ， 它 们 
的 checker 方 法 都 是 ngx_http_core_rewrite_phase， 在 这 一 阶段 中 ， 
ngx_http_handler_pt 方 法 的 返回 值 意义 与 表 10-2 也 是 完全 相同 的 ， 不 再 殉 


10.6.6 NGX HTTP POST REWRITE_ PHASE 阶段 


NGX HTTP POST_REWRITE _ PHASE 阶段 就 像 
NGX_HTTP_FIND_CONFIG_PHASE 阶 段 一 样 ， 只 能 由 HTTP 框 架 实 
现 ， 不 允许 HTTP 模 块 向 该 阶段 添加 ngx_http_handler_pt 处 理 方法 。 


NGX_HTTP_POST_REWRITE_PHASE 阶 段 的 checker 方 法 是 
ngx_http_core_post_rewrite_phase， 它 的 意义 在 于 检查 rewrite 重 写 URL 的 
次 数 不 可 以 超过 10 次 ， 以 此 防止 由 于 rewrite 死 循环 而 造成 整个 Nginx 服 
务 都 不 可 用 。 


10.6.7 NGX HTTP PREACCESS PHASE[ 阶 段 


NGX_HTTP_PREACCESS_PHASE 阶 段 一 般 用 于 对 当前 请 求 进行 限 


制 性 处 理 ， 它 的 checker 方 法 与 10.6.1 节 中 详细 描述 过 的 
ngx_http_core_generic_phase 方 法 一 样 ， 因 此 ， 在 这 一 阶段 中 执行 的 
ngx_http_handler_pt 处 理 方法 ， 其 返回 值 意义 也 与 表 10-1 是 完全 相同 的 ， 


不 再 将 述 。 


10.6.8 NGX HTTP ACCESS PHASE[ 阶 段 


NGX_HTTP ACCESS PHASE 阶 段 与 


NGX_HTTP_PREACCESS_PHASE 阶 段 大 不 相同 ， 这 主要 体现 在 它 的 


checker 方 法 是 ngx_http_core_access_phase 上 ， 这 也 就 致使 在 


NGX_HTTP_ACCESS_PHASE 阶 段 ngx_http_handler_pt 处 理 方法 的 返回 
值 有 了 新 的 意义 ， 见 表 10-3。 


表 10-3 NGX_HTTP ACCESS_PHASE 阶 段 下 HTTP 模 块 的 


ngx_http_handlet_pt 方 法 返回 值 意义 


返回 值 


NGX OK 


NGX DECLINED 
NGX_AGAIN 
NGX DONE 


NGX HTTP FORBIDDEN 


NGX HTTP UNAUTHORIZED 


NGX ERROR 
其 他 


4 

如 果 在 nginx.conf 中 配置 了 satisfy all， 那 么 将 按照 顺序 执行 下 一 个 ngx_ 
http_ handler pt 处 理 方法 ; 如 果 在 nginx.conf 中 配置 了 satisfy any， 那 么 将 执 
行 下 一 个 ngx_http phases 阶段 中 的 第 一 个 ngx_http_handler_pt 处 理 方法 

按照 顺序 执行 下 一 个 ngx_http_ handler pt 处 理 方 法 

当前 的 ngx_http_ handler pt 处 理 方法 尚未 结束 ， 这 意味 着 该 处 理 方法 在 当前 
阶段 中 有 机 会 再 次 被 调用 。 这 时 会 把 控制 权 交 还 给 事件 模块 ,下 次 可 写 事件 
发 生 时 会 再 次 执行 到 该 ngx_http_handler_pt 处 理 方法 


没 


如 果 在 nginx.conf 中 配置 了 satisfy any， 那 么 将 ngx http request t 中 的 
access code 成 员 设 为 返回 值 ， 按 照 顺序 执行 下 一 个 ngx_http handler pt 处 
理 方法 ; 如 果 在 nginx.conf 中 配置 了 satisfy all， 那 么 调用 ngx_http_finalize_ 
request 结束 请 求 


需要 调用 ngx_http_finalize_request 结束 请 求 


从 表 10-3 中 可 以 看 出 ，NGX_HTTP_ACCESS_PHASE 阶 段 实际 上 与 
nginx.conf 配 置 文件 中 的 satisfy 配 置 项 有 紧密 的 联系 ， 所 以 ， 任 何 介 入 
NGX_HTTP_ACCESS_PHASE 阶 段 的 HTTP 模 块 ， 在 实现 
ngx_http_handler_pt 方 法 时 都 需要 注意 satisfy 的 参数 ， 该 参数 可 以 由 
ngx_http_core_loc_conf t 结 构 体 中 得 到 。 





typedef struct ngx_http_core loc conf_s ngx_http_ core loc conf_t,; 
struct ngx_http_core loc conf_s { 
// 仅 可 以 取 值 为 








NGX_HTTP_SATISFY_ALL 或 者 


NGX_HTTP_SATISFY_ANY 
ngx_uint_t satisfy; 





如 果 不 根 据 所 在 location 中 的 satisfy 参 数 来 决定 返回 值 ， 那 么 可 能 造 
成 未 知 结果 。 


10.6.9 NGX HTTP POST ACCESS PHASE 阶 段 


NGX_HTTP_POST_ACCESS_PHASE 阶 段 义 是 一 个 只 能 由 HTTP 框 
架 实 现 的 阶段 ， 不 允许 HTTP 模 块 同 该 阶段 添加 ngx_http_handler_pt 处 理 
方法 。 这 个 阶段 完全 是 为 之 前 的 NGX_HTTP_ACCESS_PHASE 阶 段 服务 
的 ， 换 句 话说 ， 如 果 没 有 任何 HTTP 模 块 介入 








NGX_HTTP ACCESS _ PHASE 阶段 处 理 请 求 ， 


NGX_HTTP POST_ ACCESS _ PHASE 阶段 就 不 会 存在 。 


NGX_HTTP_POST_ ACCESS_PHASE 阶 段 的 checker 方 法 是 
ngx_http_core_post_access_phase， 它 的 工作 非常 简单 ， 就 是 检查 
ngx_http_request_t 请 求 中 的 access_code 成 员 ， 当 其 不 为 0 时 就 结束 请 求 

《表示 没有 访问 权限 ) ， 否 则 继续 执行 下 一 个 ngx_http_handler_pt 处 理 
pi 





10.6.10 NGX HTTP TRY FILES_ PHASE 阶段 


NGX_HTTP TRY _ FILES_ PHASE 阶段 也 是 一 个 只 能 由 HTTP 框 架 实 
现 的 阶段 ， 不 允许 HTTP 模 块 问 该 阶段 添加 ngx_http_handler_pt 处 理 方 
法 。 


NGX_HTTP_TRY_FILES_PHASE 阶 段 的 checker 方 法 是 
ngx_http_core_try_files_phase， 它 是 与 nginx.conf 中 的 try_files 配 置 项 密切 
相关 的 ， 如 果 try_files 后 指定 的 静态 文件 资源 中 有 一 个 可 以 访问 ， 这 时 
束 会 直接 读 取 文件 并 发 送 啊 应 给 用 户 ， 不 会 再 向 下 执行 后 续 的 阶段 ， 如 
果 所 有 的 静态 文件 资源 都 无 法 执行 ， 将 会 继续 执行 
ngx_http_phase_engine_t 中 的 下 一 个 ngx_http_handler_pt 处 理 方法 。 








10.6.11 NGX HTTP CONTENT _ PHASE 阶段 


这 是 一 个 核心 HTTP 阶 段 ， 可 以 说 大 部 分 HTTP 模 块 都 会 在 此 阶段 重 
新 定义 Nginx 服 务 器 的 行为 ， 如 第 3 章 中 提 到 的 mytest 模 块 。 
NGX_HTTP_CONTENT_PHASE 阶 段 之 所 以 被 众多 HTTP 模 块 “钟爱 ”， 
主要 基于 以 下 两 个 原因 : 











其 一 ， 以 上 9 个 阶段 主要 专注 于 4 件 基础 性 工作 : rewrite 重 写 URL、 
找到 location 配 置 块 、 判 断 请 求 是 否 具 备 访问 权限 、try_files 功 能 优先 读 
取 静 态 资 源 文 件 ， 这 4 个 工作 通常 适用 于 绝 大 部 分 请 求 ， 因 此 ， 许 多 
HTTP 模 块 希望 可 以 共享 这 9 个 阶段 中 已 经 完成 的 功能 。 


其 二 ，NGX_HTTP_CONTENT PHASE 阶段 与 其 他 阶段 都 不 相同 的 
是 ， 它 向 HITP 模 块 提 供 了 两 种 介入 该 阶段 的 方式 : 第 一 种 与 其 他 10 个 
阶段 一 样 ， 通 过 向 全 局 的 ngx_http_core_main_conf t 结 构 体 的 phases 数 组 
中 添加 ngx_http_handler_pt 处 理 方法 来 实现 ， 而 第 三 种 是 本 阶段 独 有 
的 ， 把 希望 处 理 请 求 的 ngx_http_handler_pt 方 法 设置 到 location 相 关 的 
ngx_http_core_loc_conf t 结 构 体 的 handler 指 针 中 ， 这 正 是 第 3 章 中 mytest 
例子 的 用 法 。 


上 面 所 说 的 第 一 种 方式 ， 也 是 HTTP 模块 介入 其 他 10 个 阶段 的 唯一 
方式 ， 是 通过 在 必定 会 被 调用 的 postconfiguration 方 法 同 全 局 的 





ngx_http_core_main_conf t 结 构 体 的 
phases[INGX_HTTP_CONTENT_PHASE] 动 态 数 组 添加 
ngx_http_handler_pt 处 理 方法 来 达成 的 ， 这 个 处 理 方 法 将 会 应 用 于 全 部 


的 HITP 请 求 。 


而 第 二 种 方式 是 通过 设置 ngx_http_core_loc_conf t 结 构 体 的 handler 
旨 针 来 实现 的 ， 在 10.2.3 节 中 我 们 已 经 知道 ， 每 一 个 location 都 对 应 着 一 
个 独立 的 ngx_http_core_loc_conf t 结 构 体 。 这 样 ， 我 们 就 不 必 在 必定 会 
被 调用 的 postconfiguration 方 法 中 添加 ngx_http_handler_ pt 处理 方法 了 ， 
而 可 以 选择 在 ngx_command _t 的 某 个 配置 项 (如 第 3 章 中 的 mytest 配 置 
项 ) 的 回调 方法 中 添加 处 理 方法 ， 将 当前 location 块 所 属 的 
ngx_http_core_loc_conf t 结 构 体 中 的 handler 设 置 为 ngx_http_handler_pt 处 
理 方 法 。 这 样 做 的 好 处 是 ，ngx_http_handler_pt 处 理 方法 不 再 应 用 于 所 
有 的 HTTP 请求 ， 仅 仅 当 用 户 请 求 的 URI 匹 配 了 location 时 〈 也 就 是 mytest 
配置 项 所 在 的 location ) 才 会 被 调用 。 这 也 就 意味 着 它 是 一 种 完全 不 同 
于 其 他 阶段 的 使 用 方式 。 





此 ， 当 HTTP 模 块 实现 了 某 个 ngx_http_handler_pt 处 理 方 法 并 希望 
介入 NGX_HTTP_CONTENT_PHASE 阶 段 来 处 理 用 户 请 求 时 ， 如 果 和 希望 
这 个 ngx_http_handler_pt 方 法 应 用 于 所 有 的 用 户 请 求 ， 则 应 该 在 
ngx_http_module_t 接 口 的 postconfiguration 方 法 中 ， 问 
ngx_http_core_main_conf t 结 构 体 的 
phases[INGX_HTTP_CONTENT_PHASE] 动 态 数 组 中 添加 
ngx_http_handler_pt 处 理 方法 反之， 如果 和 希望 这 个 方式 仅 应 用 于 URI 匹 
配 了 某 些 location 的 用 户 请 求 ， 则 应 该 在 一 个 location 下 配置 项 的 回调 方 





法 中 ， 把 ngx_http_handler_pt 方 法 设置 到 ngx_http_core_loc_conf t 结 构 体 
的 handler 中 。 


@ 注意 ”ngx_http_core_loc_conf_t 结 构 体 中 仅 有 一 个 handler 指 针 ， 
它 不 是 数组 ， 这 也 就 意味 着 如 果 采 用 上 述 的 第 二 种 方法 添加 
ngx_http_handler_pt 处 理 方法 ， 那 么 每 个 请 求 在 
NGX_HTTP_CONTENT_PHASE 阶 段 只 能 有 一 个 ngx_http_handler_pt 处 
理 方法 。 而 使 用 第 一 种 方法 时 是 没有 这 个 限制 的 ， 
NGX_HTTP_CONTENT_PHASE 阶 段 可 以 经 由 任意 个 HTTP 模 块 处 理 。 


当 同 时 使 用 这 两 种 方式 设置 nex_http_handler_pt 处 理 方 法 时 ， 只 
第 二 种 方式 设置 的 ngx_http_handler_pt 处 理 方法 才 会 生效 ， 也 就 是 设置 
handler 指 针 的 方式 优先 级 更 高 ， 而 第 一 种 方式 设置 的 ngx_http_handler_pt 
处 理 方法 将 不 会 生效 。 如 果 一 个 location 配 置 块 内 有 多 个 HTTP 模 块 的 配 
置 项 在 解析 过 程 都 试图 按照 第 二 种 方式 设置 hgx_http_handler_pt 处 理 方 
法 ， 那 么 后 面 的 配置 项 将 有 可 能 履 盖 前 面 的 配置 项 解析 时 对 handler 指 针 
的 设置 。 


NGX_HTTP_CONTENT PHASE 阶段 的 checker 方 法 是 
ngx_http_core_content_phase。 ngx_http_handler_pt 处 理 方法 的 返回 值 在 
以 上 两 种 方式 下 具备 了 不 同意 义 。 





在 第 一 种 方式 下 ，ngx_http_handler_pt 处 理 方法 无 论 返 回 任何 值 ， 


都 会 直接 调用 ngx_http_finalize_request 方 法 结束 请 求 。 当 然 ， 
ngx_http_finalize ea 回 值 的 不 同 未必 会 直接 结束 请 求 ， 
这 在 第 11 章 中 会 详细 介 








在 第 二 种 方式 下 ， 如 果 ngx_http_handler_pt 处 理 方法 返回 
NGX_DECLINED， 将 按 顺序 向 后 执行 下 一 个 ngx_http_handler_pt 处 理 方 
法 ;如果 返回 其 他 值 ， 则 调用 ngx_http_finalize_request 方 法 结束 请 求 。 


10.6.12 NGX HTTP LOG PHASE 阶 段 


NGX_HTTP_LOG_PHASE 阶 段 是 11 个 HTTP 处 理 阶 段 中 的 最 后 一 
个 ， 顾 名 思 义 ， 它 是 用 来 记录 日 志 的 ， 如 ngx_http_log_module 模 块 就 是 
在 这 一 阶段 中 记录 Nginx 访 问 日 志 的 。 如 果 希 望 在 请 求 的 最 后 阶段 做 一 
些 共 性 的 收尾 工作 ， 不 妨 将 ngx_http_handler_pt 处 理 方法 添加 到 这 一 阶 
段 中 。 











NGX_HTTP LOG_PHASE 阶 段 的 checker 方 法 同样 是 
ngx_http_core_generic_phase， 因 此 ， 在 这 一 阶段 中 ， 
ngx_http_handler_pt 处 理 方法 的 返回 值 意义 与 表 10-1 是 完全 相同 的 。 





10.7 HTTP 框 架 的 初始 化 流程 


本 节 将 综合 10.1 市 ~10.6 节 的 内 容 ， 完 整地 介绍 HTTP 框 染 的 初始 化 
过 程 。 实 际 上 ， 这 个 初始 化 过 程 就 在 ngx_http_module 模 块 中 ， 当 配置 文 
件 中 出 现 了 http{} 配 置 块 时 就 回调 ngx_http_block 方 法 ， 而 这 个 方法 就 包 
括 了 HTTP 框 架 的 完整 初始 化 流程 ， 如 图 10-10 所 示 。 





下 面 分 别 介绍 图 10-10 中 的 15 个 步 驰 。 


1) 按照 在 ngx_modules 数 组 中 的 顺序 ， 由 0 开始 依次 递增 地 设置 所 
有 HTTP 模 块 的 ctx_index 字 7 段 。 这 个 字段 的 值 将 决定 HTTP 模 块 应 用 于 请 
求 时 的 顺序 。 





2) 第 2 步 ~ 第 7 步 实际 上 就 是 10.2.1 节 中 描述 的 内 容 。 解 析 到 http{} 块 
时 产生 1 个 ngx_http_conf_ctx_t 结 构 体 ， 同 时 初始 化 它 的 main_conf、 
srv_conf、loc_conf 3 个 指针 数组 ， 数 组 的 容量 就 是 第 1 步 中 获取 到 的 所 
有 HTTP 模 块 的 数量 。 





3) 依次 调用 所 有 HTTP 模 块 的 create_main_conf 方 法 ， 产 生 的 配置 结 
构 体 指针 将 按照 各 模块 ctx_index 字 段 指定 的 顺序 放 入 
ngx_http_conf_ctx_t 结 构 体 的 main_conf 数 组 中 。 


4) 依次 调用 所 有 HTTP 模 块 的 create_srv_conf 方 法 ， 产 生 的 配置 结 


构 体 指针 将 按照 各 模块 ctx_index 字 段 指定 的 顺序 放 入 
ngx_http_conf_ctx_t 结 构 体 的 srv_conf 数 组 中 。 


5) 依次 调用 所 有 HTTP 模 块 的 create_ loc_conf 方 法 ， 产 生 的 配置 结 
构 体 指针 将 按照 各 模块 ctx_index 字 段 指定 的 顺序 放 入 
ngx_http_conf_ctx_t 结 构 体 的 loc_conf 数 组 中 。 


6) 依次 调用 所 有 HTTP 模 块 的 preconfiguration 方 法 。 
7) 解析 http{} 块 下 的 main 级 别 配 置 项 。 


8) 依次 调用 所 有 HTTP 模 块 的 init main_conf 方 法 。 


1 ) 初始 化 所 有 HTTP 
模块 的 ctx_index 序 号 


2 ) 分配 解 析 main 级 别 配置 项 时 存放 
HTTP 模 块 结构 体 指针 的 3 个 数组 


3 ) 调 用 所 有 HTTP 
模块 的 create_main_conf 方 法 


4) 调用 所 有 HTTP 
模块 的 create_srv_conf 方 法 


5) 调用 所 有 HTTP 
模块 的 create loc_conf 方 法 


6) 调 用 所 有 HTTP 
模块 的 preconfiguration 方 法 


7) 解析 http{} 
块 下 的 所 有 main 级 别 配置 


8 ) 调用 所 有 HTTP 
模块 的 init_main_ conf 方 法 


9 ) 合并 main 、svr 、loc 级 别 下 
server 、location 相 关 的 配置 项 














10) 构造 location 
组 成 的 静态 二 又 平衡 查找 树 











11) 初始 化 可 添加 处 理 方 法 的 
7 个 HTTP 阶 段 的 动态 数组 







12) 调用 所 有 HTTP 模 块 的 
postconfiguration 方 法 使 之 可 以 介入 HTTP 阶 段 











13) 根据 各 HTTP 模 块 介入 的 处 理 方法 构造 出 
phase_engine handlers 数组 


erver 


4) 构造 
虚拟 主机 构 成 的 支持 通 配 符 的 散 列 表 





15) 构造 监听 端口 与 server 
间 的 关联 关系 , 设置 新 连接 事件 的 回调 方法 





图 10-10 ”HTIP 框 架 的 初始 化 流程 


@G 注意 在 解析 main 级 别 配置 项 时 ， 如 果 遇 到 setvet 他 配置 块 ， 将 
会 触发 ngx_http_core_server 方 法 ， 并 开始 解析 servet 级 别 下 的 配置 项 ， 这 

过 程 可 参见 10.2.2 节 。 在 解析 stv 级 别 配 置 项 时 ， 如 果 遇 到 location 介 配 
置 块 ， 将 会 触发 nox_http_cotfe location 方法 ， 并 开始 解析 location 级 别 下 


的 配置 项 ， 这 一 过 程 可 参见 10.2.3 节 。 


9) 调用 ngx_http_merge_servers 方 法 合并 配置 项 ， 这 一 步骤 的 内 容 
与 10.2.4 节 介绍 的 多 级 别 配 置 项 合并 是 一 致 的 。 








10) 按照 10.5 节 介绍 的 方式 ， 创 建 由 location 块 构造 的 静态 二 又 平衡 
查找 树 。 


11) 在 10.6 节 中 我 们 介绍 过 ， 有 7 个 HTTP 阶 段 

(NGX_ HTTP_ POST READ _ PHASE、 
NGX_HTITP SERVER_REWRIIE_PHASE、 
NGX_HTITP_REWRIIE_PHASE、NGX_HTTIP_PREACCESS_PHASE、 
NGX_HTTP ACCESS PHASE、NGX_HTTIP_ CONTENT_PHASE、 
NGX_HTTP LOG_PHASE) 是 允许 任何 一 个 HITP 模 块 实现 自己 的 
ngx_http_handler_ pt 处理 方 法 ， 并 将 其 加 入 到 这 7 个 阶段 中 去 的 。 在 调用 
HTTP 模 块 的 postconfiguration 方 法 同 这 7 个 阶段 中 添加 处 理 方法 前 ， 需 要 
先 将 phases 数 组 中 这 7 个 阶段 里 的 handlers 动 态 数 组 初始 化 (ngx_array_t 


类 型 需要 执行 ngx_array_init 方 法 初始 化 ) ， 在 这 一 步骤 中 ， 通 过 调用 
ngx_http_init_phases 方 法 来 初始 化 这 7 个 动态 数组 。 


12) 依次 调用 所 有 HTTP 模 块 的 postconfiguration 方 法 。HTTP 模 块 可 
以 在 这 一 步骤 中 将 自己 的 ngx_http_handler_pt 处 理 方法 添加 到 以 上 7 个 


HTTP 阶 段 中 。 


13) 在 上 一 步 中 ， 各 HTTP 模 块 会 向 全 局 的 
ngx_http_core_main_conf t 结 构 体 中 的 phases 数 组 添加 处 理 方法 ， 该 数组 
中 存在 11 个 成 员 ， 每 个 成 员 都 是 动态 数组 ， 可 能 包含 任何 数量 的 处 理 方 
法 。 这 一 步骤 将 遍历 以 上 所 有 处 理 方法 ， 构 造 由 所 有 处 理 方 法 构成 的 有 
序 的 phase_engine.handlers 数 组 。 关 于 HTTP 阶 段 的 用 法 可 参见 10.6 节 。 














14) 这 一 步骤 构造 server 虚 拟 主机 构成 的 文 持 通配符 的 散 列 表 ， 可 


参见 10.4 节 的 内 容 。 


15) 这 一 步骤 构造 监听 端口 与 server 间 的 关联 关系 ， 设 置 新 连接 事 
件 的 回调 方法 为 ngx_http_init_connection， 可 参见 10.3 节 。 


以 上 15 个 步 又 就 是 HTTP 框 架 在 Nginx 的 局 动 过程 中 所 做 的 主要 工 
作 。 


10.8 小结 


本 章 介绍 了 静态 的 HITP 框 架 ， 主 要 讨论 了 http 配 置 项 的 管理 与 合并 
操作 ， 以 及 HTTP 框 架 怎样 设计 server 和 location 的 数据 结构 以 期 快速 选择 
server 和 ]location 处 理 用 户 请 求 ， 监 听 地 址 是 如 何 与 server 关 联 起 来 的 ， 同 
时 介绍 了 HTTP 的 11 个 处 理 阶段 及 其 设计 原理 和 使 用 方法 。 通 过 了 解 这 
些 内 容 ， 读 者 可 以 从 HTTP 框 架 的 角度 了 解 HTTP 模 块 的 运行 机 制 。 另 
外 ， 本 章 扩 展 了 第 3 章 中 介绍 的 单一 的 HITP 模 块 设计 方法 ， 特 别 是 根据 
10.6 节 介绍 的 内 容 ， 可 以 设计 出 更 加 强大 的 HTTP 模块 ， 深 入 地 介入 到 
任何 一 个 HTTP 处 理 阶段 中 。 


本 章 并 没有 涉及 HTTP 框 架 是 如 何 处 理 用 户 请 求 的 ，HTTP 框 架 的 动 


态 处 理 流程 将 在 第 11 章 中 介绍 。 


第 11 章 HTTP 框架 的 执行 流程 


本 章 将 介绍 动态 的 HTTP 框 架 ， 主 要 探讨 在 请 求 的 生命 周期 中 ， 基 
于 事件 驱动 的 HTTP 框 架 是 怎样 处 理 网 络 事件 以 及 怎样 集成 各 个 HTTP 模 
块 来 共同 处 理 HTTP 请 求 的 ， 同 时 ， 还 会 介绍 为 了 简化 HTTP 模 块 的 开发 
难度 而 提供 的 多 个 非 阻 塞 的 异步 方法 。 本 章 内 容 与 第 9 章 介 绍 的 事件 模 
块 密切 相关 ， 同 时 还 会 使 用 到 第 10 章 介绍 过 的 http 配 置 项 和 11 个 阶段 。 
另外 ， 本 书 第 二 部 分 讲述 了 怎样 开发 HTTP 模 块 ， 本 章 将 会 回答 为 什么 
可 以 这 样 开 发 HTTP 模 块 。 





HTTP 框 架 存 在 的 主要 目的 有 两 个 : 


. Neinx 事 件 框架 主要 是 针对 传输 层 的 TCP 的 ， 作 为 Web 服 务 器 
HTTP 模 块 需要 处 理 的 则 是 HITTP，HTTP 框 架 必须 要 针对 基于 TCP 的 事 


件 框 架 解决 好 HTTP 的 网 络 传输 、 解 析 、 组 装 等 问题 。 


` 虽然 事件 驱动 架构 在 性 能 上 是 不 错 的 ， 但 它 的 开发 效率 并 不 高 ， 
而 HTTP 模块 的 业务 通常 较 复 杂 ， 我 们 希望 HTTP 模块 在 拥有 事件 框架 的 
高 性 能 优势 的 同时 ， 尽 量 只 关注 业务 。 这 样 ，HTTP 框 架 就 需要 为 HTTP 
模块 屏蔽 事件 驱动 架构 ， 使 得 HTTP 模 块 不 需要 关心 网 络 事件 的 处 理 ， 
同时 又 能 灵活 地 介入 那 11 个 阶段 中 以 处 理 请 求 。 


根据 以 上 HTTP 框 染 的 设计 目的 ， 我 们 再 来 看 HTTP 框 染 在 动态 执行 


中 的 大 概 流程 : 先 与 客户 端 建立 TCP 连 接 ， 接 收 HTTP 请 求 行 、 头 部 并 
解析 出 它们 的 意义 ， 再 根据 nginx.conf 配 置 文件 找到 一 些 HTTP 模 块 ， 使 
其 依次 合作 着 处 理 这 个 请 求 。 同 时 为 了 简化 HTTP 模块 的 开发 ，HTTP 框 
架 还 提供 了 接收 HTTP 包 体 、 发 送 HTTP 响 应 、 派 生子 请 求 等 工具 和 方 

人 











对 于 TCP 网 络 事件 ， 可 粗略 地 分 为 可 读 事件 和 可 写 事件 ， 然 而 可 读 
事件 中 又 可 细 分 为 收 到 SYN 包 带 来 的 新 连接 事件 、 收 到 FIN 包 带 来 的 连 
接 关 闭 事件 ， 以 及 套 接 字 缓 冲 区 上 真正 收 到 TCP 流 。 可 写 事件 虽然 相对 
简单 点 ， 但 Nginx 提 供 限制 速度 功能 ， 有 时 可 写 事件 触发 时 未 必 可 以 去 
发 送 响应 。 同 时 ， 为 了 精确 地 控制 超时 ， 还 需要 把 读 / 写 事件 放置 到 定 
时 器 中 。 这 些 事件 的 管理 都 需要 依靠 HTTP 框 架 ， 这 给 HTTP 框 架 带 来 了 
复杂 性 。 在 清楚 了 解 这 些 设计 后 ， 我 们 将 对 HTTP 模 块 的 开发 有 一 个 非 
常 透彻 的 认识 ， 因 为 HTTP 模 块 完全 是 由 HTTP 框 架设 计 、 定 义 的 ， 它 就 
像 Android 应 用 程序 与 Android 操 作 系 统 间 的 关系 。 同 时 ， 深 入 了 解 HTTP 
框架 后 ， 读 者 会 明白 如 何 把 复杂 的 事件 驱动 机 制 从 关注 于 业务 的 模块 中 
分 离 ， 这 些 设 计 方 法 都 是 值得 读者 学 习 的 。 





11.1 _ HTTP 框架 执行 流程 概述 


本 章 在 介绍 HTTP 框架 的 同时 会 说 明 它 怎样 使 用 事件 模块 提供 的 操 
作 方 法 ， 在 这 之 前 ， 先 来 回顾 一 下 第 9 章 中 关于 事件 驱动 模式 的 内 容 。 











每 一 个 事件 都 是 由 ngx_event_t 结 构 体 表示 的 ， 而 TCP 连 接 则 由 
ngx_connection_t 结 构 体 表示 ，HTTP 请 求 毫 无 疑问 是 基于 一 个 TCP 连 接 
实现 的 。 每 个 TCP 连 接 包括 一 个 读 事件 和 一 个 写 事件 ， 它 们 放 在 
ngx_connection_t 中 的 read 成 员 和 write 成 员 中 。 通 过 事件 模块 提供 的 
ngx_handle_read_event 方 法 和 ngx_handle_write_event 方 法 ， 可 以 把 相应 
的 事件 添加 到 epoll 中 ， 我 们 可 以 期 待 在 满足 事件 触发 条 件 时 ，Nginx 进 
程 会 调用 ngx_event_t 事 件 的 handler 回 调 方法 执行 业务 。 而 通过 事件 模块 
提供 的 ngx_add_timer 方 法 可 以 将 上 面 的 读 事件 或 者 写 事 件 添 加 到 定时 器 
中 ， 在 满足 超时 条 件 后 ，Nginx 进 程 同样 会 调用 ngx_event_t 事 件 的 
handler 回 调 方法 执行 业务 。 








在 第 3 章 开 发 HITTP 模 块 时 ， 并 没有 看 到 事件 模块 的 影子 ， 但 HTTP 
框架 确实 是 依靠 事件 驱动 机 制 实现 的 。 基 于 这 一 点 ， 先 来 总 结 一 下 
HTTP 框 架 需 要 完成 的 最 主要 的 4 项 工作 。 





HTTP 框 染 需 要 完成 的 第 一 项 工作 是 集成 事件 驱动 机 制 ， 管 理 用 户 
发 起 的 TCP 连 接 ， 处 理 网 络 读 / 写 事件 ， 并 在 定时 需 中 处 理 请 求 超时 的 事 


件 。 这 些 内 容 将 在 11.2 节 ~11.5 节 介绍 ， 其 中 11.2 节 会 讨论 新 连接 建立 成 
功 后 HITP 框 架 的 行为 ，11.3 节 介绍 第 一 个 网 络 可 读 事件 到 达 后 HITP 框 
架 的 行为 ，11.4 节 介绍 在 没有 接收 到 完整 的 HTTP 请求 行 之 前 HTTP 框 架 
所 要 完成 的 工作 ，11.5 节 介绍 在 没有 接收 到 完整 的 HTTP 请 求 头 部 之 前 
HTTP 框 架 所 要 完成 的 工作 。 


HTTP 框 架 需 要 完成 的 第 二 项 工作 是 与 各 个 HTTP 模 块 共同 处 理 请 
求 。 实 际 上 ， 通 过 第 3 章 的 例子 我 们 已 经 知道 ， 只 有 请 求 的 URI 与 
location 配 置 匹 配 后 HITP 框 架 才 会 调度 HTTP 模块 处 理 请 求 。 而 在 第 10 
章 中 也 已 看 到 ，HTTP 框 架 定 义 了 11 个 阶段 ， 其 中 4 个 基本 的 阶段 只 能 由 
HTTP 框 架 处 理 ， 其 余 的 7 个 阶段 可 以 让 各 HTTP 模 块 介入 来 共同 处 理 请 
求 。 因 此 ，HTTP 框 染 需 要 在 这 7 个 阶段 中 调度 合适 的 HTTP 模 块 处 理 请 
求 。 第 11.6 节 中 将 介绍 HTTP 框 架 如 何 调度 HTTP 模 块 参与 到 请 求 的 处 理 
中 。 


第 三 项 工作 与 第 5 章 介 绍 过 的 subrequest 功 能 有 关 。 为 了 实现 复杂 的 
业务 ，HTTP 框 架 允 许 将 一 个 请 求 分 解 为 多 个 子 请 求 ， 当 然 ， 子 请 求 还 
可 以 继续 向 下 派生 “孙子 ”请 求 ， 这 样 束 可 以 把 复杂 的 功能 分 散 到 多 个 子 
请 求 中 ， 每 个 子 请 求 仅 专 注 于 一 个 功能 。 这 种 设计 也 是 一 种 平衡 ， 使 用 
事件 驱动 机 制 在 提高 性 能 的 同时 其 实 大 大 增加 了 程序 的 复杂 度 ， 特 别 是 
开发 复杂 功能 时 太 多 事件 的 处 理会 让 代码 混乱 不 堪 ， 而 子 请 求 的 派生 则 
可 以 降低 复 检 上 度 ， 使 得 Nginx 可 以 提供 多 样 化 的 功能 。 在 第 11.7 市 中 ， 








将 讨论 HTTP 框架 是 如 何 设计 、 实 现 subrequest 功 能 的 。 


HTTP 框 架 的 第 四 项 工作 则 是 提供 基本 的 工具 接口 ， 供 各 HTTP 模 块 
使 用 ， 诸 如 接收 HTTP 包 体 ， 以 及 发 送 HTTP 响 应 头 部 、 响 应 包 体 等 。 在 
11.8 市 中 将 说 明 HTTP 框 染 提 供 的 接收 HTTP 包 体 功 能 ，11.9 市 将 说 明 必 
送 HTTP 响 应 是 怎样 实现 的 ， 在 11.10 节 中 将 讨论 如 何 结束 HTTP 请 求 。 
为 什么 要 专门 讨论 请 求 的 结束 呢 ? 因 为 在 基于 事件 驱动 的 HTTP 框 架 
中 ， 由 于 每 个 HTTP 模 块 仅 能 在 某 一 时 刻 介 入 到 请 求 中 ， 所 以 有 时 候 它 
需要 表达 一 种 希望 * 延 后 ”结束 请 求 的 意思 ， 这 一 特性 造成 了 结束 请 求 的 
动作 十 分 复杂 ， 因 而 使 用 独立 的 一 节 来 专门 说 明 。 














本 章 的 全 部 内 容 就 是 在 探讨 如 何 完 成 以 上 四 项 工作 。 


11.2 ”新 连接 建立 时 的 行为 


当 Nginx 接 收 到 用 户 发 起 TCP 连 接 的 请 求 时 ， 事 件 框架 将 会 负责 把 
TCP 连 接 建 立 起 来 ， 如 果 TCP 连 接 成 功 建立 ，HTTP 框 架 就 会 介入 请 求 的 
处 理 了 ， 如 图 9-5 所 示 ， 在 ngx_event_accept 方 法 建立 新 连接 的 最 后 1 步 ， 
将 会 调用 ngx_listening_t 监 听 结 构 体 的 handler 方 法 。 在 10.3 节 中 讲 过 ， 
HTTP 框 架 在 初始 化 时 就 会 将 每 个 监听 ngx_listening_t 结 构 体 的 handler 方 
法 设 为 ngx_http_init_connection 方 法 ， 如 下 所 示 。 





void ngx_http_init_connection(ngx_connection t *c) 





旭 HTTP 框 架 处 理 请 求 的 第 一 步 束 在 ngx_http_init_connection 方 法 
中 ， 这 里 传 入 的 参数 c 就 是 新 建立 的 连接 。 图 11-1 列 举 了 
ngx_http_init_connection 方 法 所 做 的 主要 工作 。 





) 设置 可 该 事件 
的 回调 方法 
[检查 是 人 噩 有 可 该 的 TuP 流 


[未 接收 到 TCP 尝 
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2 ) 执行 ngx http_ init_request 





初始 化 请 求 并 处 理 TCP 流 


3) 将 可 读 事 件 加 入 到 定时 器 中 以 
监控 接 收 请 求 是 : EE 合 超 时 





4) 将 可 读 事 件 加 入 到 
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交 


图 11-1 建立 连接 成 功 后 HTTP 框 架 的 行为 


下 面 简单 解释 一 下 图 11-1 中 的 4 个 步 又 : 





1) 将 新 建立 的 连接 c 的 可 读 事件 处 理 方法 设置 为 
ngx_http_init request。 在 9.3 节 我 们 介绍 过 ngx_connection_t 结 构 体 中 会 用 
read 成 员 表 示 连 接 上 的 可 读 事件 ，write 成 员 表 示 可 写 事 件 。 读 / 写 事件 均 
使 用 ngx_event_t 结 构 体 表示 。 在 9.2 节 中 义 介绍 过 每 个 事件 发 生 时 事件 框 
架 都 会 调用 其 中 的 handler 方 法 。 这 一 步骤 实际 上 就 是 把 连接 c 的 read 读 事 
件 的 handler 方 法 设 为 ngx_http_init_request， 它 意味 着 当 用 户 在 这 个 TCP 
连接 上 发 送 的 数据 到 达 服 务 器 后 ，ngx_http_init request 方法 将 会 被 调用 


(人 参见 11.3 节 ) 。 











事实 上 ， 对 于 可 写 事 件 ， 也 会 设置 它 的 handler 回 调 方法 为 
ngx_http_empty_handler， 这 个 方法 不 会 做 任何 工作 ， 如 下 所 示 。 





void ngx_http_empty_handler(ngx_event_t *wev) 


ngx_log_debug0(NGX_LOG_ DEBUG_HTTP, wev->l0g, 0, "http empty handler"); 
return; 


} 








这 个 方法 仅 有 一 个 用 途 : 当 业 务 上 不 需要 处 理 可 写 事件 时 ， 束 把 
ngx_http_empty_handler 方 法 设置 到 连接 的 可 写 事件 的 handler 中 ， 这 样 可 
写 事件 被 定时 器 或 者 epoll 触 发 后 是 不 做 任何 工作 的 。 


@ 注意 ”下面 会 多 次 使 用 ngx_http_empty_handlet 方 法 。 


2) 如 果 新 连接 的 读 事件 ngx_event_t 结 构 体 中 的 标志 位 ready 为 1， 实 
际 上 表示 这 个 连接 对 应 的 套 接 字 绥 存 上 已 经 有 用 户 发 来 的 数据 ， 这 时 就 





可 调用 上 面 说 过 的 ngx_http_init_request 方 法 处 理 请 求 ， 参 见 11.3 节 。 


3) 在 9.7.3 节 的 表 9-5 中 我 们 介绍 过 定时 器 的 用 法 ， 在 这 一 步骤 中 将 
调用 ngx_add_timer 方 法 把 读 事件 添加 到 定时 器 中 ， 设 置 的 超时 时 间 则 是 
Oe 

未 过 client_header_timeout 时 间 后 这 个 连接 上 还 没有 用 户 数据 到 达 ， 则 会 
由 定时 器 触发 调用 读 事件 的 ngx_http_init_request 处 理 方法 。 


4) 我 们 在 9.2.1 节 中 介绍 过 ngx_handle_read_event 方 法 ， 它 可 以 将 一 
个 事件 添加 到 epoll 中 。 在 这 一 步骤 中 ， 将 调用 ngx_handle_read_event 方 
法 把 连接 c 的 可 读 事 件 添加 到 epoll 中 。 注 意 ， 这 里 并 没有 把 可 写 事件 添 
加 到 epol 中 ， 因 为 现在 不 需要 向 客户 端 发 送 任何 数据 。 











以 上 4 个 步骤 就 是 ngx_http_init_connection 方 法 的 主要 工作 ， 也 就 是 
新 连接 建立 成 功 时 HTTP 框 架 对 请 求 的 处 理 。 





11.3 ”第 一 次 可 读 事件 的 处 理 


当 TCP 连 接 上 第 一 次 出 现 可 读 事 件 时 ， 将 会 调用 
ngx_http_init request 方法 初始 化 这 个 HTTP 请 求 ， 如 下 所 示 。 


static void ngx_http_init_redquest(ngx_event_t *rev) 





实际 上 ，HTTP 框 架 并 不 会 在 连接 建立 成 功 后 就 开始 初始 化 请 求 
《参见 11.2 节 ) ， 而 是 在 这 个 连接 对 应 的 套 接 字 缓冲 区 上 确实 接收 到 了 
用 户 发 来 的 请 求 内 容 时 才 进 行 ， 这 种 设计 体现 了 Nginx 出 于 高 性 能 的 考 
虑 ， 这 样 减少 了 无 谓 的 内 存 消耗 ， 降 低 了 一 个 请 求 占用 内 存 资源 的 时 
间 。 因 此 ， 当 有 些 客户 端 建立 起 TCP 连 接 后 一 直 没 有 发 送 内 容 时 ， 
Nginx 是 不 会 为 它 分 配 内 存 的 。 





从 11.2 市 中 可 以 看 出 ， 在 有 些 情况 下 ， 当 TCP 连 接 建立 成 功 时 同时 
也 出 现 了 可 读 事件 〈 例 如 ， 在 套 接 字 设置 了 deferred 选 项 时 ， 内 核 仅 在 
套 接 字 上 确实 收 到 请 求 时 才 会 通知 epoll 调 度 事件 的 回调 方法 ) ， 这 时 
ngx_http_init request 方法 是 在 图 11-1 的 第 2 步 中 执行 的 。 当 然 ， 在 大 部 分 
情况 下 ，ngx_http_init_request 方 法 和 ngx_http_init_connection 方 法 都 是 由 
两 个 事件 “TCP 连接 建立 成 功 事件 和 连接 上 的 可 读 事件 ) 触发 调用 的 。 
图 11-2 中 展示 了 在 ngx_http_init_request 方 法 中 究竟 做 了 哪些 工作 。 
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2) 构造 ngx_http_request_t 
结构 体 并 设置 到 连接 的 data 成 员 


3 ) 找 到 监听 地 址 对 应 


J 志 人 VW 人 人 server 


4 ) 设 置 这 个 请 求 对 应 的 
http 配 置 项 


5) 重 新 设置 连接 读 事件 的 回调 方法 为 


ngx_http_process_request_line 


6) 创建 接收 1 ) 调 用 ngx_http_close_connection 
缓冲 区 方法 关闭 连接 


7) 创 建 ngx_http_request tt 
结构 体 的 内 存 池 
















8) 初始 化 ngxhttp_request 1 
结构 体 中 的 容器 


9 ) 创 建 指针 数组 以 存放 所 有 HTTP 
模块 对 该 请 求 可 能 创建 的 上 下 文 结构 体 









10) 更 新 ngx_http_ request_1t 
结构 体 的 请 求 开始 时 间 


11) 调 用 ngx_http_process_request_line 





接收 HTTP 请 求 行 


图 11-2 第 一 次 接收 到 可 读 事件 后 的 行为 


从 图 11-2 中 可 以 看 出 ， 第 一 次 读 事件 的 回调 方法 
ngx_http_init request 主要 做 了 3 件 事 : 对 请 求 构 造 ngx_http_request_t 结 构 
体 并 初始 化 部 分 参数 、 修 改 读 事件 的 回调 方法 为 
ngx_http_process_request_line 并 调用 该 方法 开始 接收 并 解析 HTTP 请 求 
行 。 下 面 详细 分 析 图 11-2 中 的 11 个 步 又: 


1) 首先 回顾 一 下 图 11-1 的 第 3 步 ， 那 里 曾经 将 读 事件 也 添加 到 了 定 
时 右 中 ， 超 时 时 间 束 是 配置 文件 中 的 client_header_timeout， 因 此 ， 首 先 
要 检查 读 事件 是 否 已 经 超时 ， 也 就 是 检查 ngx_event_t 事 件 的 timeout 成 员 
是 否 为 1。 如 果 timeout 为 1， 则 表示 接收 请 求 已 经 超时 ， 则 不 应 该 继续 处 
理 该 请 求 ， 于 是 调用 ngx_http_close_request 方 法 关闭 请 求 ， 同 时 由 











ngx_http_init_request 方 法 中 返回。ngx_http_close_request 方 法 的 详细 介 
绍 可 参见 11.10.3 节 。 


2) 在 第 3 章 介绍 HTTP 模 块 的 开发 时 曾 提 到 ， 每 个 请 求 都 会 有 一 个 
ngx_http_request_t 结 构 体 ， 所 有 的 HTTP 模 块 都 以 此 作为 核心 结构 体 来 
处 理 请 求 。 这 个 ngx_http_request_t 结 构 体 就 是 在 此 步骤 中 创建 的 ， 同 时 
还 将 这 个 关键 结构 体 的 地 址 存放 到 表示 TCP 连 接 的 ngx_connection_t 结 构 
体 中 的 data 成 员 上 。 这 一 步 中 还 会 把 表示 这 个 ngx_connection_t 结 构 体 被 
使 用 次 数 的 requests 成 员 加 1。11.3.1 节 将 会 详细 介绍 ngx_http_request_t 结 
构 体 。 


3) 从 10.3 节 可 以 看 出 ， 配 置 文件 的 每 个 server{} 块 中 都 可 以 针对 不 
同 的 本 机 耳 地 址 监听 同一 个 端口 ， 事 实 上 每 一 个 监听 对 象 ngx_listening ft 
都 会 对 应 着 监听 这 个 端口 的 所 有 监听 地 址 。 回 顾 一 下 8.3.1 闻 ， 
ngx_listening _t 结 构 体 中 有 一 个 servers 指 针 ， 在 HTTP 框架 中 ， 它 指向 监 
听 这 一 端口 的 所 有 监听 地 址 ， 而 每 个 监听 地 址 也 包含 了 其 所 属 server 块 
的 配置 项 ， 如 下 所 示 。 





typedef struct { 
ngx_http_core_ srv_conf_t *default_ server,; 
ngx_http_virtual names _t *virtual names,; 
} ngx_http_addr_conf_t; 











default_server 也 就 是 这 个 监听 地 址 对 应 的 server 块 配置 信息 ， 在 第 10 
章 中 我 们 曾经 介绍 过 ngx_http_core_srv_conf t 结 构 体 是 如 何 管理 配置 信 
息 的 。 这 一 步 中 将 会 遍历 ngx_listening t 结 构 体 的 servers 指 向 的 数组 ， 找 
到 合适 的 监听 地 址 ， 然 后 找到 默认 的 server 虚 拟 主机 对 应 的 
ngx_http_core_srv_conf t 配 置 结构 体 。 


4) 在 第 2 步 建 立 好 的 ngx_http_request_t 结 构 体 中 ，main_conf、 
srv_conf、loc_conf 这 3 个 成 员 表 示 这 个 请 求 对 应 的 main、srv、loc 级 别 的 
配置 项 ， 这 时 会 通过 刚刚 获取 到 的 默认 的 ngx_http_core_srv_conf t 结 构 
体 设置 (10.2 节 中 介绍 过 ，ngx_http_core_srv_conf t 结 构 体 具有 一 个 
ngx_http_conf_ctx_t 类 型 的 成 员 ctx， 从 这 里 可 以 获取 到 3 个 级 别 的 配置 项 
指针 数组 ) 。 


5) 第 一 次 读 事件 的 回调 方法 是 ngx_http_init_request， 它 仅 用 于 初 
始 化 请 求 ， 之 后 的 恋 事 件 意味 痢 接收 到 请 求 内 容 ， 显 而 易 见 ， 它 的 回调 
方法 是 需要 改变 一 下 的 ， 即 在 这 一 步 中 将 把 这 个 读 事件 的 回调 方法 设 为 


ngx_http_process_request_line， 这 个 方法 将 会 负责 接收 并 解析 出 完整 的 








HTTP 请 求 行 。 





6) 读 事件 被 触发 ， 其 实 就 意味 着 对 应 的 套 接 字 缓冲 区 上 已 经 接收 
到 用 户 的 请 求 了 ， 这 时 需要 在 用 户 态 的 进程 空间 分 配 内 存 ， 用 来 把 内 核 
缓冲 区 上 的 TCP 流 复制 到 用 户 态 的 内 存 中 ， 并 使 用 状态 机 来 解析 它 是 否 
是 合法 的 、 完 整 的 HTTP 请 求 。 这 一 步 将 在 ngx_connection_t 的 内 存 池 中 
分 配 一 块 内 存 〈 读 者 可 以 思考 为 何 没有 在 ngx_http_request_t 结 构 体 的 内 
存 池 中 分 配 接收 请 求 的 缓存 ) ， 内 存 块 的 大 小 与 nginx.conf 文 件 中 的 
client_header_buffer_size 配 置 项 参数 一 致 ，ngx_connection_t 结 构 体 的 
buffer 指 针 以 及 ngx_http_request_t 结 构 体 的 header_in 指 针 共同 指向 这 块 内 
存 缓冲 区 。 这 个 header ip 缓 冲 区 《除了 在 11.8.1 节 外 ) 将 负责 接收 用 户 
发 送 来 的 请 求 内 容 。 当 这 个 TCP 连 接 复 用 于 其 他 HTTP 请 求 时 ， 这 个 
buffer 指 针 指 向 的 内 存 仍然 是 可 用 的 ， 新 的 HITP 请 求 初始 化 执行 到 这 一 
步 时 ， 就 不 用 再 次 由 ngx_connection_t 的 内 存 池 分 配 内 存 了 。 








7) ngx_http_request_t 结 构 体 同样 有 一 个 内 存 池 ，HTTP 模 块 更 应 该 
在 ngx_http_request_t 结 构 体 的 pool 内 存 池 上 申请 新 的 内 存 ， 这 样 请 求 结 
束 时 《连接 可 能 会 被 复 用 ) 该 内 存 池 中 分 配 的 内 存 都 会 及 时 回收 。 这 一 


步 中 将 会 创建 这 个 内 存 池 ， 内 存 池 的 初始 大 小 由 nginx.conf 文 件 中 的 
request_pool_size 配 置 项 参数 决定 。 这 个 内 存 池 只 会 在 11.10.2 节 中 介绍 


的 ngx_http_free_request 方 法 中 销毁 。 


8) 初始 化 ngx_http_request_t 结 构 体 中 的 部 分 容器 ， 如 headers_out 结 
构 体 中 的 ngx_list_t 类 型 的 headers 链 表 、variables 数 组 等 。 


9) 在 4.5 节 曾经 讲 过 ， 每 个 HTTP 模 块 都 可 以 针对 一 个 请 求 设置 上 
下 文 结构 体 ， 并 通过 ngx_http_set_ctx 和 ngx_http_get_module_ctx 宏 来 设 
置 和 获取 上 上下文。 那么 ， 这 些 HTTP 模 块 针 对 请 求 设置 的 上 下 文 结构 体 
指针 ， 实 际 上 是 保存 到 ngx_http_request_t 结 构 体 的 ctx 指 针 数 组 中 的 。 在 
这 一 步骤 中 ， 会 分 配 一 个 具有 ngx_http_max_module (HTTP 模 块 的 总 
数 ) 个 成 员 的 指针 数组 ， 也 就 是 说 ， 为 每 个 HTTP 模 块 都 提供 一 个 位 置 
存放 上 下 文 结构 体 的 指针 。 


10〉ngx_http_request_t 结 构 体 中 有 两 个 成 员 表示 这 个 请 求 的 开始 处 
理 时 间 : start_sec 成 员 和 start_msec 成 员 。 这 一 步 中 将 会 初始 化 这 两 个 成 


员 。 在 11.9.2 节 中 将 会 看 到 这 两 个 成 员 的 用 法 ， 它 们 会 为 限 速 功 能 服 


11) 调用 ngx_http_process_request_line 方 法 开始 接收 、 解 析 HTTP 请 
求 行 O 


以 上 步骤 构成 了 ngx_http_init_request 方 法 的 主要 内 容 ， 其 中 构造 的 





ngx_http_request_t 结 构 体 在 接 下 来 的 小 节 中 会 详细 介绍 。 


从 第 3 章 开 始 ， 我 们 已 经 多 次 见 过 ngx_http_request_t 结 构 体 了 ， 但 
大 多 是 站 在 HTTP 模 块 的 角度 来 思考 如 何 使 用 Nginx 已 经 为 我 们 构造 好 的 
ngx_http_request_t 结 构 体 。 本 节 再 次 介绍 ngx_http_request_t 结 构 体 ， 则 
是 站 在 HITTP 框 架 的 角度 来 思考 如 何 完 成 HTTP 框 架 的 基本 功能 。 下 面 首 
先 说 明 它 与 HITP 框 架 密切 相关 的 成 员 。 





typedef struct ngx_http_request_s ngx_http_redquest tt， 
struct ngx_http_request _s { 
// 这 个 请 求 对 应 的 客户 端 连接 


ngx_connection_t *connection; 
// 指向 存放 所 有 


HTTP 模 块 的 上 下 文 结构 体 的 指针 数组 


void **ctx; 
// 指向 请 求 对 应 的 存放 


main 级 别 配置 结构 体 的 指针 数组 


void **main_conf; 
// 指向 请 求 对 应 的 存放 


Srv 级 别 配置 结构 体 的 指针 数组 


void **srv_conf; 
// 指向 请 求 对 应 的 存放 


loc 级 别 配置 结构 体 的 指针 数组 


void **]oc_conf; 
/* 在 接收 完 


HTTP 头 部 ， 第 一 次 在 业务 上 处 理 


HTTP 请 求 时 ， 


HTTP 框 架 提供 的 处 理 方法 是 


ngx_http_process_request。 但 如 果 该 方法 无 法 一 次 处 理 完 该 请 求 的 全 部 业务 ， 在 归还 控制 权 到 


epoll1 事 件 模 块 后， 该 请 求 再 次 被 回调 时 ， 将 通过 





ngx_http_request_handler 方 法 来 处 理 ， 而 这 个 方法 中 对 于 可 读 事件 的 处 理 就 是 调用 


read_event_handler 处 理 请 求 。 也 就 是 说 ， 


HTTP 模 块 希望 在 底层 处 理 请 求 的 读 事 件 时 ， 重 新 实现 


read_event_handler 方 法 


*/ 
ngx_http_event_handler_pt read event_handler; 
/与 


read_event_handler 回 调 方法 类 似 ， 如 果 





ngx_http_request_handler 方 法 判断 当前 事件 是 可 写 事 件 ， 则 调用 


write_event_handler 处 理 请 求 。 


ngx_http_request_handler 的 流程 可 参见 图 


11-7*/ 
ngx_http_event_handler_pt write event_handler,; 
// Upstream 机 制 用 到 的 结构 体 ， 在 第 


12 章 中 会 详细 说 明 


ngx_http_upstream t *upstream; 
/* 表 示 这 个 请 求 的 内 存 池 ， 在 


ngx_http_free_request 方 法 中 销毁 。 它 与 


ngx_connection_t 中 的 内 存 池 意义 不 同 ， 当 请 求 释放 时 ， 


TCP 连 接 可 能 并 没有 关闭 ， 这 时 请 求 的 内 存 池 会 销毁 ， 但 


ngx_connection 七 的 内 存 池 并 不 会 销毁 


*/ 
ngx_pool t *pool; 
// 用 于 接收 


HTTP 请 求 内 容 的 缓冲 区 ， 主要 用 于 接收 


HTTP 头 部 


ngx_buf_t *header_in; 
/*ngx_http_process_request_headers 方 法 在 接收 、 解 析 完 


HTTP 请 求 的 头 部 后 ， 会 把 解析 完 的 每 一 个 


HTTP 头 部 加 入 到 


headers_in 的 


headers 链 表 中 ， 同 时 会 构造 


headers_in 中 的 其 他 成 员 


*/ 
ngx_http_headers_in t headers_in; 
/*HTTP 模 块 会 把 想 要 发 送 的 


HTTP 响 应 信息 放 到 


headers_out 中 ， 期 望 


HTTP 框 架 将 


headers_out 中 的 成 员 序 列 化 为 


HTTP 响 应 包 发 送 给 用 户 


*/ 
ngx_http_headers_ out_t headers out,; 
// 接收 


HTTP 请 求 中 包 体 的 数据 结构 ， 详 见 


11.8 节 


ngx_http_request_ body_t *request_body; 
// 延迟 关闭 连接 的 时 间 


time t lingering_time; 
/* 当 前 请 求 初始 化 时 的 时 间 。 


start_sec 是 格林 威 治 时 间 


1970 年 


1 月 


1 日 凌晨 


8 秒 到 当前 时 间 的 秒 数 。 如 果 这 个 请 求 是 子 请 求 ， 则 该 时 间 是 子 请 求 的 生成 时 间 ; 如 果 这 个 请 求 是 用 户 发 来 的 请 求 ， 


TCP 连 接 后 ， 第 一 次 接收 到 可 读 事件 时 的 时 间 


3 六 
time_t start_sec,; 
7Z/ 与 


Start_sec 配 合 使 用 ， 表 示 相 对 于 


Start_set 秒 的 毫秒 偏 移 量 


ngx_msec_t start_msec 
/A/* 以 下 


9 个 成 员 都 是 


ngx_http_process_request_1ine 方 法 在 接收 、 解 析 


HTTP 请 求 行 时 解析 出 的 信息 ， 其 意义 在 第 


3 章 已 经 详细 描述 过 ， 这 里 不 再 介绍 


*% 
ngx_uint_t method; 
ngx_uint_t http_version; 
ngx_str_t request_line,; 
ngx_str_t uri; 
ngx_str_t args; 
ngx_str_t exten; 
ngx_str_t unparsed_uri; 
ngx_str_t method_name; 
ngx_str_t http_protocol; 
/* 表 示 需 要 发 送 给 客户 端的 


HTTP 吻 应 。 


Out 中 保存 着 由 


headers_out 中 序列 化 后 的 表示 


HTTP 头 部 的 


TCP 流 。 在 调用 


ngx_http_output_filter 方 法 后 ， 


OUt 中 还 会 保存 待 发 送 的 


HTTP 包 体 ， 它 是 实现 异步 发 送 


HTTP 响 应 的 关键 ， 参 见 


11.9 节 


*/ 
ngx_chain _t *out; 
/* 当 前 请 求 既 可 能 是 用 户 发 来 的 请 求 ， 也 可 能 是 派生 出 的 子 请 求 ， 而 


main 则 标识 一 系列 相关 的 派生 子 请 求 的 原始 请 求 ， 我 们 一 般 可 通过 


main 和 当前 请 求 的 地 址 是 否 相 等 来 判断 当前 请 求 是 否 为 用 户 发 来 的 原始 请 求 


*/ 
ngx_http_request_t *main; 
// 当前 请 求 的 父 请 求 。 注 意 ， 父 请 求 未 必 是 原始 请 求 


ngx_http_request_t *parent 
/与 


Subrequest 子 请 求 相 关 的 功能 。 在 


11.10.6 节 中 会 看 到 它们 在 


HTTP 框 架 中 的 部 分 使 用 方式 


* 

/ 
ngx_http_postponed_request_t *postponed; 
ngx_http_post_subrequest_t *post_ subrequest; 
/* 所 有 的 子 请 求 都 是 通过 


posted_requests 这 个 单 链表 来 链接 起 来 的 ， 执 行 


post 子 请 求 时 调用 的 


ngx_http_run_posted_requests 方 法 就 是 通过 遍历 该 单 链表 来 执行 子 请 求 的 





*/ 
ngx_http_posted _ request_t *posted requests,; 
/* 全 局 的 


ngx_http_phase_engine_t 结 构 体 中 定义 了 一 个 





ngx_http_phase_handler_t 回 调 方 法 组 成 的 数组 ， 而 


phase_handler 成 员 则 与 该 数组 配合 使 用 ， 表 示 请 求 下 次 应 当 执 行 以 


phase_handler 作 为 序号 指定 的 数组 中 的 回调 方法 。 


HTTP 框 架 正 是 以 这 种 方式 把 各 个 


HTTP 模 块 集成 起 来 处 理 请 求 的 


*/ 
ngx_int_t phase_handler; 
/表示 


NGX_HTTP_CONTENT_PHASE 阶 段 提供 给 


HTTP 模 块 处 理 请 求 的 一 种 方式 ， 


content_handler 指 向 


HTTP 模 块 实现 的 请 求 处 理 方法 ， 详 见 


11.6.4 节 


* 
/ 
ngx_http_handler_pt content_handler,; 
/* 在 


NGX_HTTP_ACCESS_PHASE 阶 段 需要 判断 请 求 是 否 具有 访问 权限 时 ， 通 过 


access_code 来 传递 


HTTP 模 块 的 


handler 回 调 方法 的 返回 值 ， 如 果 


access_code 为 


上 ， 则 表示 请 求 具备 访问 权限 ， 反 之 则 说 明 请 求 不 具备 访问 权限 


*y 
ngx_uint_t access_code,; 
// HTTP 请 求 的 全 部 长 度 ， 包 括 


HTTP 包 体 


off t request_length,; 
/在 这 个 请 求 中 如 果 打 开 了 某 些 资源 ， 并 需要 在 请 求 结束 时 释放 ， 那 么 都 需要 在 把 定义 的 释放 资源 方法 添加 3 


Cleanup 成 员 中 ， 详 见 


11.10.2 节 


*/ 
ngx_http_cleanup_t *cleanup; 
/* 表 示 当 前 请 求 的 引用 次 数 。 例 如 ， 在 使 用 


Subrequest 功 能 时 ， 依 附 在 这 个 请 求 上 的 子 请 求 数目 会 返回 到 


Count 上， 每 增加 一 个 子 请 求 ， 


COUNt 数 就 要 加 


1。 其 中 任何 一 个 子 请 求 派生 出 新 的 子 请 求 时 ， 对 应 的 原始 请 求 ( 


main 指 针 指 向 的 请 求 ) 的 


count 值 都 要 加 


1。 又 如 ， 当 我 们 接收 


HTTP 包 体 时 ， 由 于 这 也 是 一 个 异步 调用 ， 所 以 


COUNt 上 也 需要 加 


1， 这 样 在 结束 请 求 时 〈 


11.19 节 中 介绍 ) ， 就 不 会 在 


Count 引 用 计数 未 清 零 时 销毁 请 求 。 可 以 参见 


11.10.3 节 的 


ngx_http_close_request 方 法 


*/ 
unsigned count:8; 
// 阻塞 标志 位 ， 目 前 仅 由 


aio 使 用 ， 本 章 不 涉及 


unsigned blocked:8,; 
// 标志 位 ， 为 


1 时 表示 当前 请 求 正在 使 用 异步 文件 


IO 
unsigned aio:1; 
// 标志 位 ， 为 
1 时 表示 
URL 发 生 过 
rewrite 重 写 


unsigned uri_changed:1; 
/* 表 示 使 用 


rewrite 重 写 


URL 的 次 数 。 因 为 目前 最 多 可 以 更 改 


10 次 ， 所 以 


Uri_changes 初 始 化 为 


11， 而 每 重 写 


URL 一 次 就 把 


uri_changes 减 


1, 一 旦 


uri_changes 等 于 


9， 则 向 用 户 返回 失败 


*/ 
unsigned uri_changes:4; 
/* 标 志 位 ， 为 


1 时 表示 当前 请 求 是 


keepalive 请 求 


* 
/ 
unsigned keepalive:1; 
/* 延 迟 关 闭 标志 位 ， 为 


1 时 表示 需要 延迟 关闭 。 例 如 ， 在 接收 完 


HTTP 头 部 时 如 果 发 现 包 体 存在 ， 该 标志 位 会 设 为 


1， 而 放弃 接收 包 体 时 则 会 设 为 


0， 参 见 

11.8 节 

WA 
unsigned lingering close:1; 
// 标志 位 ， 为 

1 时 表示 正在 丢弃 


HTTP 请 求 中 的 包 体 


unsigned discard_body:1; 
/* 标 志 位 ， 为 


1 时 表示 请 求 的 当前 状态 是 在 做 内 部 跳 转 。 具 体 用 法 可 参见 图 


11-5 中 的 第 
4 步 和 第 
5 步 

*/ 


unsigned internal:1; 
/* 标 志 位 ， 为 


1 时 表示 发 送 给 客户 端的 


HTTP 响 应 头 部 已 经 发 送 。 在 调用 


ngx_http_send_header 方 法 (参见 


11.9.1 节 ) 后 ， 若 已 经 成 功 地 启动 响应 头 部 发 送 流程 ， 该 标志 位 就 会 置 为 


1， 用 来 防止 反复 地 发 送 头 部 


2 
unsigned header_sent:1; 
// 表示 缓冲 中 是 否 有 待 发 送 内 容 的 标志 位 
unsigned buffered:4; 
// 状态 机 解析 
HTTP 时 使 用 


State 来 表示 当前 的 解析 状态 


ngx_uint_t state 


}; 





以 上 介绍 的 ngx_http_request_t 结 构 体 成 员 ， 大 多 都 会 出 现在 本 章 后 续 章 节 中 ， 读 者 在 看 : 


11.4 接收 HTTP 请 求 行 


接收 HTTP 请 求 行 这 个 行为 必然 是 在 初始 化 请 求 之 后 发 生 的 。 在 图 
11-2 的 第 11 步 表明 已 经 调用 了 ngx_http_process_request_line 方 法 来 接收 
HTTP 请 求 行 。HTTP 请 求 行 的 格式 如 下 所 示 。 





GET /uri HTTP/1.1 








可 以 看 出 ， 这 样 的 请 求 行 长 度 是 不 定 的 ， 它 与 URI 长 度 相 关 ， 这 意 
味 着 在 读 事件 被 触发 时 ， 内 核 套 接 字 缓 冲 区 的 大 小 未 必 足 够 接收 到 全 部 
的 HTTP 请 求 行 ， 由 此 可 以 得 出 结论 : 调用 一 次 
ngx_http_process_request_line 方 法 不 一 定 能 够 做 完 这 项 工作 。 所 以 ， 
ngx_http_process_request_line 方 法 也 会 作为 读 事 件 的 回调 方法 ， 它 可 能 
会 被 epoll 这 个 事件 驱动 机 制 多 次 调度 ， 反 复 地 接收 TCP 流 并 使 用 状态 机 
解析 它们 ， 直 到 确认 接收 到 了 完整 的 HITP 请 求 行 ， 这 个 阶段 才 算 完 
成 ， 才 会 进入 下 一 个 阶段 接收 HTTP 头 部 。 


此 ，ngx_http_process_request_line 方 法 与 ngx_http_init_connection 
方法 、ngx_http_init_request 方 法 都 不 一 样 ， 后 两 种 方法 在 一 个 请 求 中 只 
会 被 调用 一 次 ， 而 ngx_http_process_request_line 方 法 则 至 少 会 被 调用 一 
次 ， 而 到 底 会 调用 多 少 次 则 取决 于 客户 病 的 行为 及 网 络 中 IP 包 的 转发 


等 。 图 11-3 展 示 了 ngx_http_process_request_line 方 法 的 流程 ， 需 要 注意 





其 中 对 各 个 步骤 的 摘 述 ， 其 中 有 些 步 骤 会 导致 
ngX_http_process_request_line 方 法 和 暂时 结束 ， 但 会 在 下 一 次 读 事件 来 临 
时 继续 被 调用 。 


图 11-3 描 述 了 ngx_http_process_request_line 方 法 的 主要 流程 ， 由 于 
它 涉 及 了 TCP 字 符 流 的 接收 、 解 析 ， 因 此 会 相对 复杂 一 些 ， 下 面 详细 描 


述 一 下 这 12 个 步骤 : 


1) 首先 检查 这 个 读 事件 是 否 已 经 超时 ， 超 时 时 间 仍 然 是 nginx.conf 
配置 文件 中 指定 的 dient_header_timeout。 如 果 ngx_event_t 事 件 的 timeout 
标志 为 1， 则 认为 接收 HTTP 请 求 已 经 超时 ， 调 用 ngx_http_close_request 
方法 《参见 11.10.3 节 ) 关闭 请 求 ， 同 时 由 ngx_http_process_request_line 
方法 中 返回 。 


2) 在 当前 读 事 件 未 超时 的 情况 下 ， 检 查 header_in 接 收 缓冲 区 ( 参 
见 图 11-2 的 第 6 步 ) 中 是 否 还 有 未 解析 的 字符 流 。 第 一 次 调用 
ngx_http_process_request_line 方 法 时 缓冲 区 里 必然 是 空 的 ， 这 时 会 调用 
封装 的 recv 方 法 把 Linux 内 核 套 接 字 缓冲 区 中 的 TCP 流 复制 到 header_in 组 
冲 区 中 。header_in 的 类 型 是 ngx_buf t， 它 的 pos 成 员 和 last 成 员 指 向 的 地 
址 之 间 的 内 存 就 是 接收 到 的 还 未 解析 的 字符 流 。 如 有 果 header_ in 接收 缓冲 
区 中 还 有 未 解析 的 字符 流 ， 则 不 会 调用 recv 方 法 接收 ， 而 是 跳 到 下 面 的 


第 4 步 继 续 执 行 。 


3) 在 第 2 步 中 兽 经 调用 封装 的 recv 方 法 ， 如 果 返 回 值 表 示 连 接 出 现 
错误 或 者 客户 端 已 经 关闭 连接 ， 则 路 转 到 第 1 步 ， 如果 返 回 值 表 示 接 收 
到 客户 并 发送 的 字符 流 ， 则 跳 转 到 第 5 步 中 解析 ; 如 末 返 回 值 表示 本 次 
没有 接收 到 TCP 流 ， 需 要 继续 检测 这 个 该 事件 ， 则 开始 本 步骤 的 执行 。 


首先 检查 这 个 读 事 件 是 否 在 定时 器 中 ， 如 有 果 已 经 在 定时 器 ， 则 跳 转 
到 第 4 步 ， 反 之 ， 调 用 ngx_add_timer 方 法 向 定时 器 添加 这 个 读 事件 。 


4) 调用 ngx_handle_read_event 方 法 把 该 读 事 件 添加 到 epoll 中 ， 同 时 
ngx_http_process_request_line 方 法 结束 。 


[检查 是 否 接收 HTTP 请 求 超时 ] 


















[没有 超时 ] 


[接收 缓冲 区 中 没有 未 解析 的 数据 ] 
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妇 TCP 流 


[ 读 缓 冲 区 仍 有 空闲 ] ”[ 检 查 接收 方法 的 返回 值 ] 


[接收 缓冲 区 在 还 有 


未 解析 的 数据 ] 
£5 0 1 lk | 
i [连接 错误 或 客户 端 关闭 连接 ] 






[如 果 已 经 接收 到 数据 ] [ 读 事 件 没有 在 定时 器 中 ] 


3) 将 读 事件 添加 
到 定时 器 中 





[ 读 事件 已 经 存在 于 定时 器 中 | 





5) 用 状态 机 解析 已 接收 
到 的 字符 流 


[需要 继续 接收 数据 | XX [解析 失败 ] 
WM A [解析 得 到 请 求 line] 




















7) 设 置 解析 成 功 的 
URI 等 参 





1 ) 调 用 ngx_http_close_request 


厂 贱 全 5 


[HTTP 1.0 版 本 以 下 ] 


[HTTP10 或 者 HTTP1.1 版 本 ] 








10) 初始 化 存放 HTTP 
头 部 的 容器 












8) 找 到 请 求 对 应 的 
server 






1 重新 设置 可 读 


日 可 亡 站 


12) 调 用 ngx_htt i nt PMA 
头 部 





9) 调 用 ngx_http_process_request 
理 二 3 





图 11-3 接收、 解析 HTTP 请 求 行 的 流程 图 


5) 在 第 2 步 接收 到 字符 流 后 ， 将 在 这 一 步骤 用 状态 机 解析 已 经 接收 
到 的 TCP 字 符 流 ， 确 认 其 是 否 构成 完整 的 HTTP 请 求 行 。 这 个 状态 机 解 
析 请 求 行 的 方法 叫做 ngx_http_parse_request_line， 它 使 用 
ngx_http_request_t 结 构 体 中 的 state 成 员 来 保存 解析 状态 ， 如 下 所 示 。 





ngx_int_t ngx_http_parse_request_ line(ngx_http_request _t *r, ngx_buf_t *b) 








这 里 传 入 的 参数 b 是 header_in 绥 冲 区 ， 返 回 值 主要 有 3 类 : 返回 
NGX_OK 表 示 成 功 地 解析 到 完整 的 HTTP 请 求 行 ， 返 回 NGX_AGAIN 表 
示 目 前 接收 到 的 字符 流 不 足以 构成 完成 的 请 求 行 ， 还 需要 接收 更 多 的 字 
符 流 :; 返回 NGX_HTTP_PARSE_INVALID_REQUEST 或 者 
NGX_HTTP_PARSE_INVALID_09_METHOD 等 其 他 值 时 表示 接收 到 非 
法 的 请 求 行 。 


6) 如 果 ngx_http_parse_request_line 方 法 返回 NGX_OK， 表 示 成 功 地 
接收 到 完整 的 请 求 行 ， 这 时 跳 转 到 第 7 步 继 续 执 行 。 


如 果 ngx_http_parse_request_line 方 法 返回 NGX_AGAIN， 则 表示 和 需 
要 接收 更 多 的 字符 流 ， 这 时 需要 对 header_in 缓 冲 区 做 判断 ， 检 查 是 否 还 
有 空闲 的 内 存 ， 如 果 还 有 未 使 用 的 内 存 可 以 继续 接收 字符 流 ， 则 跳 转 到 
第 2 步 ， 检 查 绥 冲 区 是 否 有 未 解析 的 字符 流 ， 否 则 调用 
ngx_http_alloc_large_header_buffer 方 法 分 配 更 大 的 接收 缓冲 区 。 到 底 分 
配 多 大 了 呢 ? 这 由 nginx.conf 文 件 中 的 large_client_header_buffers 配 置 项 指 





如 果 ngx_http_parse_request_line 方 法 返回 
NGX_HTTP_PARSE_INVALID_REQUEST 或 者 
NGX_HTTP_PARSE_INVALID_09_METHOD 等 其 他 值 ， 那 么 HTTP 框 
架 将 不 再 处 理 非 法 请 求 ， 跳 转 到 第 1 步 关 闭 请 求 。 


7) 在 接收 到 完整 的 HTTP 请 求 行 后 ， 首 先 要 把 请 求 行 中 的 信息 如 方 
法 名 、URI 及 其 参数 、HTTP 版 本 等 信息 设置 到 ngx_http_request_t 结 构 体 


的 相应 成 员 中 (如 request_line、uri、method_name、unparsed_uri、 











http_protocol、exten、args 等 ) ， 在 3.6.2 市 开发 HTTP 模 块 时 曾 介 绍 过 这 
些 成 员 的 用 法 ， 它 们 就 是 在 这 一 步 中 被 赋值 的 。 





8) 如 果 在 第 7 步 得 到 的 http_version 成 员 中 显示 用 户 请 求 的 HTTP 版 
本 小 于 1.0 (如 HTTP 0.9 版 本 ) ， 其 处 理 过 程 将 与 HTTP 1.0 和 HTTP 1.1 
的 完全 不 同 ， 它 不 会 有 接收 HTTP 头 部 这 一 步骤 。 这 时 将 会 调用 
ngx_http_find_virtual_server 方 法 寻找 到 相应 的 虚拟 主机 ， 回 顾 一 下 在 
10.4 节 中 虚拟 主机 是 使 用 散 列 表 来 进行 管理 的 ， 
ngx_http_find_virtual_server 方 法 就 是 用 于 在 散 列 表 中 检索 出 虚拟 主机 。 





如 果 http_version 成 员 中 显示 出 用 户 请 求 的 HTTP 版 本 是 1.0 或 者 更 高 
的 版 本 ， 则 直接 跳 到 第 10 步 中 执行 。 


9) 继续 处 理 HTTP 版 本 小 于 1.0 的 情形 。 由 于 不 需要 再 次 接收 HTTP 


头 部 ， 调 用 ngx_http_process_request 方 法 开始 处 理 请 求 〈 参 见 11.6 节 ) 。 


10) 初始 化 ngx_http_request_t 结 构 体 中 存放 HTTP 头 部 的 一 些 容 
器 ， 如 headers_in 结 构 体 中 ngx_list_t 类 型 的 headers 链 表 容 器 、 
ngx_array_t 类 型 的 cookies 动 态 数 组 容器 等 ， 为 下 一 步 接收 HTTP 头 部 做 
好 准备 《参见 11.5 节 ) 。 


11〉 由 于 已 经 接收 完 HTTP 请 求 行 ， 因 此 这 时 把 读 事件 的 回调 方法 
由 ngx_http_process_request_line 改 为 ngx_http_process_request_headers， 


准备 接收 HITTP 头 部 。 


12) 调用 ngx_http_process_request_headers 方 法 开始 接收 HTTP 头 


接收 完 FTTP 请 求 行 后 ， 在 下 一 节 中 我 们 将 分 析 接 收 HTTP 头 部 这 一 


步骤 。 


11.5 接收 HTTP 头 部 


本 将 描述 接收 HTTP 头 部 这 一 阶段 ， 该 阶段 是 通过 
ngx_http_process_request_headers 方 法 实现 的 ， 该 方法 将 被 设置 为 连接 的 
读 事件 回调 方法 ， 在 接收 较 大 的 HTTP 头 部 时 ， 它 有 可 能 会 被 反复 多 次 
地 调用 。HTTP 头 部 类 似 下 面 加 了 下 划 线 的 字符 串 ， 而 
ngx_http_process_request_headers 方 法 的 目的 就 在 于 接收 到 当前 请 求全 部 
的 HITP 头 部 。 





GET /uri HTTP/1.1 
cred: xxx 
username: ttt 
content-length: 4 
test 








可 以 看 出 ，HTTP 头 部 也 属于 可 变 长 度 的 字符 串 ， 它 与 HTTP 请 求 行 
和 包 体 间 都 是 通过 换行 符 来 区 分 的 。 同 时 ， 它 与 解析 HTTP 请 求 行 一 
样 ， 都 需要 使 用 状态 机 来 解析 数据 。 既 然 HTTP 请 求 行 和 头 部 都 是 变 长 
的 ， 对 它们 的 总 长 度 当 然 是 有 限制 的 。 从 图 11-3 的 第 6 步 可 以 看 出 ， 当 
最 初 分 配 的 大 小 为 client_header_buffer_size 的 缓冲 区 且 无 法 容纳 下 完整 
的 HTTP 请 求 行 或 者 头 部 时 ， 会 再 次 分 配 大 小 为 
large_client_header_buffers (这 两 个 值 些 为 nginx.conf 文 件 中 指定 的 配置 
项 ) 的 缓冲 区 ， 同 时 会 将 原先 缓冲 区 的 内 容 复制 到 新 的 缓冲 区 中 。 所 
以 ， 这 意味 着 可 变 长 度 的 HTTP 请 求 行 加 上 HTTP 头 部 的 长 度 总 和 不 能 超 











过 large_client_header_buffers 指 定 的 字 节 数 ， 否 则 Nginx 将 会 报错 。 


先 来 看 看 图 11-4 中 展示 的 HITP 框 架 使 用 
ngX_http_process_request_headers 方 法 接收 、 解 析 HTTP 头 部 的 流程 。 





图 11-4 中 分 支 较 多 ， 下 面 详 细 地 解释 一 下 图 中 的 11 个 步骤 。 





1) 如 同 接收 http 请 求 行 一 样 ， 首 先 检 查 当 前 的 读 事件 是 否 已 经 超 
时 。 检 查 方法 仍然 是 检查 事件 的 timeout 标 志 位 ， 如 果 为 1， 则 表示 接收 
请 求 已 经 超时 ， 这 时 调用 ngx_http_close_request 方 法 关闭 连接 ， 同 时 退 


出 ngx_http_process_request_headers 方 法 。 


2) 检查 接收 HTTP 请 求 涉 部 的 header_in 绥 冲 区 是 否 用 尽 ， 当 
header_in 组 冲 区 的 pos 成 员 指 向 了 end 成 员 时 ， 表 示 已 经 用 尽 ， 这 时 需要 
调用 ngx_http_alloc_large_header_buffer 方 法 分 配 更 大 、 更 多 的 缓冲 区 ， 
如 同 图 11-3 中 的 第 6 步 。 如 果 缓 冲 区 还 没有 用 尽 ， 则 跳 到 第 4 步 中 执行 。 





3) 事实 上 ，ngx_http_alloc_large_header_buffer 方 法 会 有 3 种 返回 
值 ， 其 中 NGX_OK 表 示 成 功 分 配 到 更 大 的 缓冲 区 ， 可 以 继续 接收 客户 端 
发 来 的 字符 流 ; NGX_DECLINED 表 示 已 经 达到 缓冲 区 大 小 的 上 限 ， 无 
法 分 配 更 大 的 缓冲 区 ，NGX_ERROR 表 示 出 现 错误 。 所 以 ， 当 返回 
NGX_ERROR 时 ， 跳 转 到 第 1 步 执行 ， 而 当 返 回 NGX_DECLINED 时 ， 需 








要 问 用 户 返回 错误 并 且 同 时 退出 ngx_http_process_request_headers 方 法 ， 
错误 码 由 宏 NGX_HTTP REQUEST_HEADER_TOO_LARGE 表 示 ， 也 就 





是 494， 实 际 上 这 一 过 程 是 通过 调用 ngx_http_finalize_request 方 法 来 实现 
的 《参见 11.10.6 节 ) ; 如 果 返 回 NGX_OK， 则 继续 第 4 步 执行 。 








[检查 是 否 接 收 请 求 超时 ] 


[header in 缓冲 区 已 经 用 尽 ] 
已 经 超时 ] 


[header_in 还 有 空闲 内 存 接收 字符 流 ] 






[分 配 缓存 错误 ] 










分 配 到 更 大 的 缓 有 | 





3) 回 客户 端 发 送 
494 响 应 并 结束 请 求 













人 在 缓 祁 区 上 上 
本 [需要 继续 接收 才能 解析 ] 
[连接 错误 或 用 户 关闭 连接 ] 
[需要 继续 接收 数据 ] 





[检查 recv 方 法 返回 值 ] 
















5) 将 读 事 件 添加 到 
定时 器 所 


与 epoll 





6) 用 状态 机 解析 已 接收 
到 的 字符 流 














[检查 状态 机 返回 值 ] 





7 ) 设置 解析 出 
的 头骨 





根据 host 头 部 找到 
对 应 的 server 1) 调 用 ngx_ Ee close_request 


闭 请 求 





10) 检查 部 分 头 部 
信息 是 否 合法 


11) 调 用 ngx_http_ process_ request 
方法 处 理 请 求 


图 11-4 ngx_http_process_request_headers 方 法 接收 HTTP 头 部 的 流程 图 


4) 接收 客户 端 发 来 的 字符 流 ， 即 把 内 核 套 接 字 绥 冲 区 上 的 字符 流 





接收 到 header ip 缓冲 区 中 。 这 一 过 程 是 通过 调用 封装 过 的 recv 方 法 实现 
的 ， 如 果 过 程 中 出 现 错误 ， 仍 然 跳 转 到 第 1 步 执行 ， 如 果 没 有 接收 到 数 
据 ， 但 错误 码 表明 仍然 需要 再 次 接收 数据 ， 则 跳 转 到 第 5 步 执行 ， 如 果 
成 功 接收 到 数据 ， 则 跳 转 到 第 6 步 执行 。 


5) 这 个 步骤 将 该 读 事 件 添加 到 epol 和 定时 器 中 ， 实 际 上 就 是 图 11- 
3 中 第 3 步 和 第 4 步 的 合并 ， 不 再 歼 述 。 





6) 调用 ngx_http_parse_header_line 方 法 解析 缓冲 区 中 的 字符 流 。 这 
种 方法 有 3 个 返回 值 : 返回 NGX_OK 时 ， 表 示 解 析出 一 行 HITP 头 部 ， 这 
时 需要 跳 转 到 第 7 步 设置 这 行 已 经 解析 出 的 HITP 头 部 ， 返 回 
NGX_HTTP_PARSE_HEADER_DONE 时 ， 表 示 已 经 解析 出 了 完整 的 
HTTP 头 部 ， 这 时 可 以 准备 开始 处 理 HITTP 请 求 了 〈11.6 节 介绍 ) ; 返回 
NGX_AGAIN 时 ， 表 示 还 需要 接收 到 更 多 的 字符 流 才 能 继续 解析 ， 这 时 
需要 跳 转 到 第 2 步 去 接收 更 多 的 字符 流 ; 除 此 之 外 的 错误 情况 ， 将 跳 转 
到 第 8 步 发 送 400 错 误 给 客户 端 。 


7) 将 解析 出 的 HITP 头 部 设置 到 表示 ngx_http_request_{t 结 构 体 
headers_ipn 成 员 的 headers 链 表 中 。 从 3.6.3 节 中 可 以 看 出 ， 开 发 HTTP 模块 
时 获取 到 的 HITP 头 部 就 是 在 这 个 步骤 中 设置 的 。 


8) 当 调 用 ngx_http_parse_header_line 方 法 解析 字符 串 构成 的 HTTP 
， 是 有 可 能 过 到 非法 的 或 者 Nginx 当 前 版 本 不 支持 的 HTTP 头 部 的 ， 这 


er ee! 





时 该 方法 会 返回 错误 ， 于 是 调用 ngx_http_finalize_request 方 法 ， 向 客户 
端 发 送 NGX_HTTP_BAD_REQUEST 宏 对 应 的 400 错 误 码 响应 。 


9) 当 ngx_http_parse_header_line 方 法 认为 已 经 解析 到 完整 的 HTTP 
头 部 时 ， 将 会 根据 HTTP 头 部 中 的 host 字 段 情况 ， 调 用 
ngx_http_find_virtual_server 方 法 找到 对 应 的 虚拟 主机 配置 块 ， 也 束 是 第 
10 章 中 介绍 过 的 ngx_http_core_srv_conf t 结 构 体 。 这 一 步 会 导致 图 11-2 
的 第 4 步 中 ngx_http_request_t 结 构 体 里 的 srv_conf、loc_conf 成 员 被 重新 
设置 ， 以 指向 正确 的 虚拟 主机 。 





10) 这 一 步骤 将 检查 以 上 步骤 中 接收 解析 出 的 HITP 头 部 是 否 合 
法 ， 主 要 包括 以 下 几 项 : 如 果 HTTP 版 本 为 1.1， 则 host 头 部 不 可 以 为 
空 ， 人 否则 返回 400 Bad Request 错 误 啊 应 给 客户 端 ; 如果 传递 了 Content- 
Length 头 部 ， 那 么 它 必 须 是 合法 的 数字 ， 人 否则 会 返回 400 Length 
Required 错 误 啊 应 给 客户 端 ;， 如 果 请 求 使 用 了 PUT 方法 ， 那 么 必须 传递 
Content-Length 头 部 ， 人 否则 会 返回 400 Length Required 错 误 啊 应 给 客户 


端 。 


11) 调用 ngx_http_process_request 方 法 开始 使 用 各 HTTP 模 块 正 式 地 
在 业务 上 处 理 HTTP 请 求 。 





以 上 11 步 又 仅 专注 于 接收 并 解析 出 全 部 的 HITP 头 部 ， 同 时 检查 它 
们 的 合法 性 ， 并 将 解析 出 的 HITP 头 部 设置 到 ngx_http_request_t 结 构 体 


里 的 合适 位 置 。 接 下 来 开始 讨论 如 何 使 用 以 上 两 节 中 已 经 解析 好 的 
HTTP 请 求 行 和 头 部 。 





11.6 ”处 理 HTTP 请 求 





在 接收 到 完整 的 HTTP 头 部 后 ， 已 经 拥有 足够 的 必要 信息 开始 在 业 
务 上 处 理 HITP 请 求 了 。 本 节 将 说 明 HTTP 框 架 是 如 何 召集 负责 具体 功能 
的 各 HITTP 模 块 合 作 处 理 请 求 的 。 在 图 11-4 的 第 11 步 及 图 11-3 的 第 10 步 
中 ， 最 后 都 是 通过 调用 ngx_http_process_request 方 法 开始 处 理 请 求 ， 本 
节 将 讨论 ngx_http_process_request 方 法 的 流程 ， 而 且 
ngx_http_process_request 方 法 只 是 处 理 请 求 的 开始 ， 对 于 基于 事件 驱动 
的 异步 HITP 框 架 来 说 ， 处 理 请 求 并 不 是 一 步 可 以 完成 的 ， 所 以 我 们 也 
会 讨论 后 续 TCP 连 接 上 的 回调 方法 ngx_http_request_handler 的 流程 。 首 
先 来 看 看 接收 完 ETTP 头 部 后 ngx_http_process_request 方 法 所 做 的 事情 ， 
如 图 11-5 所 示 。 

















[检查 TCP 连 接 的 读 事 件 是 否 在 定时 器 中 ] 









1) 把 读 事件 从 
定时 器 中 移 除 


2) 重新 设置 连接 上 
读 / 写 事件 的 处 理 方法 










3) 设置 请 求 的 
read_event_handler 方 法 
[检查 请 求 的 internal 标志 位 ] 

[internal 为 1] 4) 设置 phase_handler 序 号 为 
a server_rewrite_index 


[internal 为 0] 





5 ) 设 置 请 求 的 
phase_handler 序号 为 0 


6) 设置 请 求 的 write_event_handler 


调 方 法 


7) 调用 ngx_http_core_run_phases 
方法 集成 HTTP 模 块 处 理 请 求 


8 ) 调 用 ngx_http_run_posted_requests 
方法 执行 post 请 求 





鲁 


图 11-5 ”ngx_http_process_request 处 理 HTTP 请 求 的 流程 图 


下 面 详细 介绍 图 11-.5 中 的 8 个 步骤。 





1) 由 于 现在 已 经 开始 准备 调用 各 HTTP 模 块 处 理 请 求 了 ， 因 此 不 再 
存在 接收 HTTP 请 求 头 部 超时 的 问题 ， 那 就 需要 从 定时 器 中 把 当前 连接 
的 读 事 件 移 除了 。 检 查 读 事件 对 应 的 timer_set 标 志 位 ， 为 1 时 表示 读 事 
件 已 经 添加 到 定时 器 中 了 ， 这 时 需要 调用 ngx_del _timer 从 定时 器 中 移 除 
读 事 件 ， 如 果 timer_set 标 志 位 为 0， 则 直接 执行 第 2 步 。 





2) 从 现在 开始 不 会 再 需要 接收 HTTP 请 求 行 或 者 头 部 ， 所 以 需要 重 
新 设置 当前 连接 读 / 写 事件 的 回调 方法 。 在 这 一 步骤 中 ， 将 同时 把 读 事 
件 、 写 事件 的 回调 方法 都 设置 为 ngx_http_request_handler 方 法 ， 在 下 面 
的 图 11-7 中 会 介绍 到 这 个 方法 ， 请 求 的 后 续 处 理 都 是 通过 
ngx_http_request_handler 方 法 进行 的 。 


3) 设置 ngx_http_request_t 结 构 体 的 read_event_handler 方 法 为 
ngx_http_block_reading。 前 面 11.3 节 中 曾 介 绍 过 read_event_handler 方 
法 ， 当 再 次 有 读 事 件 到 来 时 ， 将 会 调用 read_event_handler 方 法 处 理 请 
求 。 而 这 里 将 它 设 置 为 ngx_http_block_reading 方 法 ， 这 个 方法 可 认为 不 
做 任何 事 ， 它 的 意义 在 于 ， 目 前 已 经 开始 处 理 HTTP 请 求 ， 除 非 某 个 
HTTP 模 块 重新 设置 了 read_event_handler 方 法 ， 否 则 任何 读 事件 都 将 得 
不 到 处 理 ， 也 可 以 认为 读 事 件 被 阻塞 了 。 








4) 检查 ngx_http_request_t 结 构 体 的 internal 标 志 位 ， 如 果 internal 为 


0， 则 继续 执行 第 5 步 ， 如 果 internal 标 志 位 为 1， 则 表示 请 求 当 前 需要 做 
内 部 跳 转 ， 将 要 把 结构 体 中 的 phase_handler 序 号 置 为 
server_rewrite_index。 先 来 回顾 一 下 10.6.1 节 ， 注 意 
ngx_http_phase_engine_t 结 构 体 中 的 handlers 动 态 数组 中 保存 了 请 求 需要 
经 历 的 所 有 回调 方法 ， 而 server_rewrite_index 则 是 handlers 数 组 中 
NGX_HTTP_SERVER_REWRITE_PHASE 处 理 阶 段 的 第 一 个 
ngx_http_phase_handler_t 回 调 方 法 所 处 的 位 置 。 








究竟 handlers 数 组 是 怎么 使 用 的 呢 ? 事 实 上 ， 它 要 配合 着 
ngx_http_request_t 结 构 体 的 phase_handler 序 号 使 用 ， 由 phase_handler 指 
定 着 请 求 将 要 执行 的 handlers 数 组 中 的 方法 位 置 。 注 意 ，handlers 数 组 中 
的 方法 都 是 由 各 个 HTTP 模 块 实现 的 ， 这 就 是 所 有 HTTP 模 块 能 够 共同 处 
理 请 求 的 原因 。 


在 这 一 步骤 中 ， 把 phase_handler 序 号 设 为 server_rewrite_index， 这 
意味 着 无 论 之 前 执行 到 哪 一 个 阶段 ， 马 上 都 要 重新 从 
NGX_HTTP_SERVER_REWRITE_PHASE 阶 段 开 始 再 次 执行 ， 这 是 
Nginx 的 请 求 可 以 反复 rewrite 重 定 辣 的 基础 。 





5) 当 internal 标 志 位 为 0 时 ， 表 示 不 需要 重 定 同 〈( 如 刚 开始 处 理 请 求 
时 ) ， 将 phase_handler 序 号 置 为 0%， 意 味 着 从 ngx_http_phase_engine_t 指 
定数 组 的 第 一 个 回调 方法 开始 执行 《参见 10.6 节 ， 了 解 
ngx_http_phase_engine_t 是 如 何 将 各 HTTP 模 块 的 回调 方法 构造 成 handlers 





数组 的 ) 。 


6) 设置 ngx_http_request_t 结 构 体 的 write _event_handler 成 员 为 
ngx_http_core_run_phases 方 法 。 如 同 read_event_handler 方 法 一 样 ， 在 图 
11-7 中 可 以 看 到 write_event_handler 方 法 是 如 何 被 调用 的 。 


7) 执行 hgx_http_core_run_phases 方 法 ， 其 流程 如 图 11-6 所 示 。 


8) 调用 ngx_http_run_posted_requests 方 法 执行 post 请 求 ， 参 见 11.7 


上 述 第 7 步调 用 了 ngx_http_core_run_phases 方 法 ， 该 方法 将 开始 调 
用 各 个 HITP 模 块 共同 处 理 请 求 。 在 第 10 章 我 们 讨论 过 HTTP 框 架 的 初始 
化 ， 在 这 一 过 程 中 是 允许 各 个 HTTP 模 块 将 自己 的 处 理 方法 按照 11 个 
ngx_http_phases 阶 段 添 加 到 全 局 的 ngx_http_core_main_conf t 结 构 体 中 
的 。 下 面 简单 地 回顾 一 下 它 的 定义 ， 如 下 上 所 示 。 











typedef struct { 


// HTTP 框 架 初始 化 后 各 个 
HTTP 模 块 构造 的 处 理 方法 将 组 成 


phase_engine 

ngx_http_phase_engine_t phase_engine,; 
} ngx_http_core _ main conf_t; 
typedef struct { 

/* 由 








ngx_http_phase_handler_t 结 构 体 构成 的 数组 ， 每 一 个 数组 成 员 代表 着 一 个 


HTTP 模 块 所 添加 的 一 个 处 理 方法 


Wy 
ngx_http_phase_handler t *handlers,; 


} ngx_http_phase_engine_t; 
typedef struct ngx_http_phase_ handler_s ngx_http_phase handler_t; 
struct ngx_http_phase handler _s { 

/每 个 








handler 方 法 必须 对 应 着 一 个 
Checker 方 法 ， 这 个 
checker 方 法 由 
HTTP 框 架 实 现 


* 

/ 
ngx_http_phase_ handler_ pt checker; 
// 各 个 


HTTP 模 块 实现 的 方法 


ngx_http_handler_pt handler; 


}; 





可 以 看 到 ， 根 据 ngx_http_core_main_conf t 结 构 体 的 phase_engine 成 
员 即 可 依次 调用 各 个 HTTP 模块 来 共同 处 理 一 个 请 求 。 下 面 看 看 网 11-6 
中 展示 的 ngx_http_core_run_phases 方 法 的 流程 。 


全 


是 人 否 实现 『checker 方 法 | 


| 实现 Jehecker 方法 ] 





执行 phase_handler 序号 指定 的 [返回 非 NGX_OK| 
checker 方法 


[未 实现 checker 方 法 | [检查 check 方 法 返回 值 | 





[checker 方 法 返回 NCX_OKI 





图 11-6 ”ngx_http_core_run_phases 方 法 的 执行 流程 


在 图 11-6 中 仅 会 执行 每 个 ngxX_http_phase_handler t 处 理 阶 段 的 
checker 方 法 ， 而 不 会 执行 handler 方 法 ， 其 原因 已 在 10.6 节 讲 过 ， 这 是 因 
为 handler 方 法 其 实 仅 能 在 checker 方 法 中 被 调用 ， 而 且 checker 方 法 由 
HTTP 框 架 实 现 ， 所 以 可 以 控制 各 HTTP 模 块 实现 的 处 理 方法 在 不 同 的 阶 
段 中 采用 不 同 的 调用 行为 。 再 来 简单 地 看 一 下 调用 的 源 代码 。 





void ngx_http_core_run_phases(ngx_http_redquest_t *r) 





ngx_int_t rc; 

ngx_http_phase_handler_t *ph,; 

ngx_http_core_ main conf_t *cmcf; 

cmcf = ngx_http_get_ module main conf(r, ngx_http_core module); 
ph = cmcf->phase_engine.handlers; 








while (ph[r->phase_ handler].checker) { 
rc = ph[r->phase_handler].checker(r, &ph[r->phase_handler]); 
If (rc == NGX_OK) { 
return 





可 以 看 到 ，ngx_http_request_t 结 构 体 中 的 phase_handler 成 员 将 决定 
执行 到 哪 一 阶段 ， 以 及 下 一 阶段 应 当 执行 哪个 HITP 模 块 实现 的 内 容 。 
在 图 11-5 的 第 4 步 和 第 5 步 中 可 以 看 到 请 求 的 phase_handler 成 员 会 被 重 
置 ， 而 HTTP 框 架 实现 的 checker 方 法 也 会 修改 phase_handler 成 员 的 值 。 
表 11-1 列 出 了 HTTP 框 架 实 现 的 所 有 checker 方 法 ， 如 下 所 示 。 





表 11-1 HTTP 框 架 为 11 个 阶段 实现 的 checker 方 法 



































阶段 名 称 checker 方法 

NGX HTTP POST READ PHASE ngx http_core generic phase 
NGX HTTP SERVER REWRITE PHASE ngx http_core_ rewrite phase 
NGX HTTP FIND CONFIG PHASE ngx_ http_core find config phase 
NGX HTTP REWRITE PHASE ngx http_core_ rewrite phase 
NGX HTTP POST REWRITE PHASE ngx http_core_ post rewrite _ phase 
NGX. HIIP PREACCESS. PHASE ngx http_core generic phase 
NGX HTTP ACCESS PHASE ngx http_core access phase 
NGX: HTTP POST AGCCESS. PHASE ngx_ http_core post access phase 
NGX. HTTP TRY FILES. PHASE ngx http_ core try files phase 
NGX HTTP CONTENT PHASE ngx http_core_content phase 
NGX HTTP LOG PHASE ngx http_core generic phase 





我 们 在 10.6 节 中 曾经 详细 介绍 过 HTTP 阶 段 。 在 11 个 阶段 中 其 中 7 个 
是 允许 各 个 HTTP 模块 向 阶段 中 任意 添加 自己 实现 的 handler 处 理 方法 
的 ， 但 同一 个 阶段 中 的 所 有 handler 处 理 方法 都 拥有 相同 的 checker 方 法 ， 
见 表 11-1。 我 们 知道 ， 每 个 阶段 中 处 理 方法 的 返回 值 都 会 以 不 同 的 方式 


影响 HTTP 框 架 的 行为 ， 而 在 图 11-6 中 也 可 以 看 到 ，checker 方 法 在 返回 
NGX_OK 和 其 他 值 时 也 会 导致 不 同 的 结果 (每 个 checker 方 法 的 返回 值 
实际 上 与 handler 处 理 方 法 的 返回 是 相关 的 ， 参 见 10.6.2 市 ~10.6.12 市 中 对 
各 个 阶段 的 说 明 ) 。 当 checker 方 法 的 返回 值 非 NGX_OK 时 ， 意 味 着 向 
下 执行 phase_engine 中 的 各 处 理 方 法 ， 反 之， 当 任 何 一 个 checker 方 法 返 
回 NGX_OK 时 ， 意 味 着 把 控制 权 交还 给 Nginx 的 事件 模块 ， 由 它 根据 事 
件 〈 网 络 事件 、 定 时 器 事件 、 异 步 JO 事 件 等 ) 再 次 调度 请 求 。 然 而 ， 

个 请 求 多 半 需 要 Nginx 事 件 模块 多 次 地 调度 HTTP 模块 处 理 ， 这 时 就 要 
看 在 图 11-5 中 第 2 步 设置 的 读 / 写 事件 的 回调 方法 ngx_http_request_handler 
的 功能 了 ， 如 图 11-7 所 示 。 











1) 由 触发 事件 中 取出 


ngx_http _request_t 结构 体 
[检查 当前 事件 是 可 读 事 件 还 是 可 写 事件 ] 





[ 当前 事件 可 读 ] [当前 事件 可 写 ] 








2 ) 执行 write _event_handler 方 法 


3) 执行 read_event_handle! 方 法 





4 ) 调用 ngx http_run_posted_requests 方 法 执行 post 请 求 


图 11-7 ngx_http_tequest_handlet 方 法 的 执行 流程 





通 种 来 说 ， 在 接收 完 HITP 头 部 后 ， 是 无 法 在 一 次 Nginx 框 娘 的 调度 
中 处 理 完 一 个 请 求 的 。 在 第 一 次 接收 完 HTTP 头 部 后 ，HTTP 框 染 将 调度 
ngx_http_process_request 方 法 开始 处 理 请 求 ， 这 时 根据 图 11-6 中 的 流程 
可 以 看 到 ， 如 末 茶 个 checker 方 法 返回 了 NGX_OK， 则 将 会 把 控制 权 交 
还 给 Nginx 框 架 。 当 这 个 请 求 上 对 应 的 事件 再 次 触发 时 ，HTTP 框 架 将 不 
会 再 调度 ngx_http_process_request 方 法 处 理 请 求 ， 而 是 由 
ngx_http_request_handler 方 法 开始 处 理 请 求 。 下 面 来 看 看 图 11-7 中 列 出 
的 ngx_http_request_handler 方 法 的 流程 : 











1) ngx_http_request_handler 是 HTTP 请 求 上 读 / 写 事件 的 回调 方法 。 
在 ngx_event_t 结 构 体 表 示 的 事件 中 ，data 成 员 指 向 了 这 个 事件 对 应 的 
ngx_connection_t 连 接 ， 而 根据 11.3 节 中 的 内 容 可 以 看 到 ， 在 HTTP 框 架 
的 ngx_connection_t 结 构 体 中 的 data 成 员 则 指向 了 ngx_http_request_t 结 构 
体 。 毫 无 疑问 ， 只 有 拥有 了 ngx_http_request_t 结 构 体 才 可 以 处 理 HITTP 
请 求 ， 而 第 一 个 步 又 是 从 事件 中 取出 ngx_http_request_t 结 构 体 。 








2) 检查 这 个 事件 的 write 可 写 标 志 ， 如 果 write 标 志 为 1， 则 调用 
ngx_http_request_t 结 构 体 中 的 write_event_handler 方 法 。 注 意 ， 我 们 在 
ngx_http_handler 方 法 中 《〈 即 图 11-5 的 第 6 步 ) 已 经 将 write_event_handler 
设置 为 ngx_http_core_run_phases 方 法 ， 而 一 般 我 们 开发 的 不 太 复 杂 的 


HTTP 模 块 是 不 会 重新 设置 write_event_handler 方 法 的 ， 因 此 ， 一 旦 有 可 
写 事 件 时 ， 束 会 继续 按照 图 11-6 的 流程 执行 ngx_http_core_run_phases 方 
法 ， 并 继续 按 阶段 调用 各 个 HITTP 模 块 实现 的 方法 处 理 请 求 。 


3) 调用 ngx_http_request_t 结 构 体 中 的 read_event_handler 方 法 。 注 意 
比较 第 2 步 和 第 3 步 ， 如 果 一 个 事件 的 该 写 标志 同时 为 1] 时， 仅 
write_event_handler 方 法 会 被 调用 ， 即 可 写 事件 的 处 理 优先 于 可 读 事 件 
(这 正 是 Nginx 高 性 能 设计 的 体现 ， 优 先 处 理 可 写 事件 可 以 尽快 释放 内 
存 ， 尽 量 保持 各 HTTP 模 块 少 使 用 内 存 以 提高 并 及 能 力 ) 。 











4) 调用 ngx_http_run_posted_requests 方 法 执行 post 请 求 ， 参 见 11.7 


以 上 重点 讨论 了 ngx_http_process_request 和 ngx_http_request_handler 
这 两 个 方法 ， 其 中 ngx_http_process_request 方 法 负责 在 接收 完 HITP 头 部 
后 ， 第 一 次 与 各 个 HITP 醒 块 共同 按 阶 段 处 理 请 求 ， 而 对 于 
ngx_http_request_handler 方 法 ， 如 果 ngx_http_process_request 没 能 处 理 完 
请 求 ， 这 个 请 求 上 的 事件 再 次 被 触发 ， 那 就 将 由 此 方法 继续 处 理 了 。 


这 两 个 方法 的 共通 之 处 在 于 ， 它 们 都 会 先 按 阶段 调用 各 个 HITP 模 
块 处 理 请 求 ， 再 处 理 post 请 求 。 关 于 post 请 求 的 内 容 下 文 会 介绍 ， 而 按 
阶段 处 理 请 求实 际 上 就 是 图 11-6 中 描述 的 流程 ， 也 就 是 通过 每 个 阶段 的 
checker 方 法 来 实现 。 在 表 11-1 中 可 以 看 到 ， 在 各 个 HTTP 模 块 能 够 介入 





的 7 个 阶段 中 ， 实 际 上 共享 了 4 个 checker 方 法 : 
ngx_http_core_generic phase、 ngx_http_core rewrite_phase.、 
ngx_http_core_access_phase、ngx_http_core_content_phase， 在 10.6 市 中 
我 们 曾经 简单 地 介绍 过 它们 。 


这 4 个 checker 方 法 的 主要 任务 在 于 ， 根 据 phase_handler 执 行 菏 个 
HTTP 模块 实现 的 回调 方法 ， 并 根据 方法 的 返回 值 决定 : 当前 阶段 已 经 
完全 结束 了 吗 ? 下 次 要 执行 的 回调 方法 是 哪 一 个 ?究竟 是 立刻 执行 下 一 
个 回调 方法 还 是 先 把 控制 权 交 还 给 epoll? 下 面 通 过 介绍 这 4 个 checker 方 
法 来 回答 上 述 3 个 问题 (其 他 checker 方 法 仅 由 HTTP 框 架 使 用 ， 这 里 不 再 
详细 介绍 ) 。 











11.6.1 ngx_http_core generic phase 


从 表 11-1 中 可 以 看 出 ， 有 3 个 HTTP 阶 段 都 使 用 了 
ngx_http_core_generic_phase 作 为 它们 的 checker 方 法 ， 这 意味 着 任何 试图 
在 NGX_HTTP POST_READ_PHASE、 

NGX_HTTP PREACCESS_PHASE、NGX_HTTP LOG_PHASE 这 3 个 阶 
段 处 理 请 求 的 HTTP 模 块 都 需要 了 解 ngx_http_core_generic_phase 方 法 到 
底 做 了 些 什 么 。 图 11-8 中 描述 了 ngx_http_core_generic_phase 方 法 的 流 
程 ， 可 以 看 到 ， 在 调用 了 当前 阶段 的 handler 方 法 后 ， 根 据 返回 值 的 不 同 
可 能 导致 4 种 不 同 的 结 


下 面 说 明 图 11-8 中 所 列 的 5 个 步骤 。 


1) 首先 调用 HTTP 模 块 实现 的 handler 方 法 ， 这 个 方法 的 实现 当然 是 
不 允许 有 阻塞 操作 的 ， 它 会 立刻 返回 。 根 据 它 的 返回 值 类 型 ， 将 会 有 4 
种 不 同 的 结果 : 返回 NGX_OK 时 直接 跳 转 到 第 2 步 执行 ， 返 回 
NGX_DECLINED 时 跳 转 到 第 3 步 执 行 ， 返 回 NGX_AGAIN 或 者 
NGX_DONE 时 跳 转 到 第 4 步 执 行 ， 返回 其 他 值 时 跳 转 到 第 5 步 执 行 。 


2) 如 果 HTTP 模 块 实现 的 handler 方 法 返回 NGX_OK， 这 意味 着 当前 
阶段 已 经 执行 完毕 ， 需 要 跳 转 到 下 一 个 阶段 执行 。 例 如 ， 在 
NGX_HTTP_ACCESS_PHASE 阶 段 中 可 能 有 两 个 HTTP 模 块 都 注册 了 回 
调 方法 ， 在 执行 第 1 个 HTTP 模块 的 回调 方法 时 ， 如 果 它 返回 了 
NGX_OK， 那 么 就 不 再 执行 第 2 个 HTTP 模 块 实现 的 回调 方法 了 ， 而 是 跳 
转 到 下 一 个 阶段 (如 NGX_HTTP_POST_ACCESS_PHASE) 开始 执行 。 
注意 ， 此 时 ngx_http_core_generic_phase 方 法 会 返回 NGX_AGAIN， 从 图 
11-6 中 可 以 看 到 ， 非 NGX_OK 的 返回 值 不 会 使 HTTP 框 架 把 进程 控制 权 
交还 给 epoll 等 事件 模块 ， 而 是 会 继续 立刻 执行 请 求 的 后 续 处 理 方 法 。 


1 ) 调 用 HTTP 模 块 实现 的 





handler 方 法 处 理 请 求 


[检查 handle 访 法 的 返回 值 ] 


[返回 NGX_OK] 





2 ) 将 phase_handler 设 为 [返回 NGX_DECLINED] 





next 并 返回 NGX_AGAIN 


[返回 NGX_AGAIN 或 者 NGX_DONE] 


[返回 其 他 值 ] 3) phase_handler++ 





并 返回 NGX_AGAIN 


4) 直接 返回 NGX_OR 


5 ) 调用 ngx_ http_finalize _request 





结束 请 求 并 返回 NGX_OK 


© 


图 11-8 ngx_http_core_genetic_phase 方 法 的 执行 流程 


3) 如 果 handler 方 法 返回 NGX_DECLINED， 则 会 执行 下 一 个 回调 方 


法 。 继 续 第 2 步 中 的 例子 ， 在 NGX_HTTP_ACCESS_PHASE 阶 段 ， 第 1 个 
HTTP 模 块 的 回调 方法 返回 NGX_DECLINED 后 ， 下 一 个 将 要 执行 的 方法 
仍然 属于 NGX_HTTP_ACCESS_PHASE 阶 段 ， 即 第 2 个 HTTP 模 块 实现 的 
回调 方法 。 注 意 ， 这 时 ngx_http_core_generic_phase 返 回 的 仍然 是 
NGX_AGAIN， 它 意味 着 HTTP 框 架 会 紧 接着 继续 执行 请 求 的 后 续 处 理 


帮 : 


4) 如 果 handler 方 法 返回 NGX_AGAIN 或 者 NGX_DONE， 则 意味 着 
刚才 的 handler 方 法 无 法 在 这 一 次 调度 中 处 理 完 这 一 个 阶段 ， 它 需要 多 次 
调度 才能 完成 ， 也 就 是 说 ， 刚 刚 执行 过 的 handler 方 法 希望 : 如 果 请 求 对 
应 的 事件 再 次 被 触发 时 ， 将 由 ngx_http_request_handler 通 过 
ngx_http_core_run_phases 再 次 调用 这 个 handler 方 法 。 直 接 返 回 NGX_OK 
会 使 得 HTTP 框 架 立 刻 把 控制 权 交 还 给 epoll 事 件 框架 ， 不 再 处 理 当 前 请 
求 ， 唯 有 这 个 请 求 上 的 事件 再 次 被 触发 才 会 继续 执行 。 


1 ) 调用 HTTP 模 块 实现 的 
handler 人 处理 方法 


[检查 handle 方 法 的 返回 值 ] 








[返回 NGX_DECLINED] 


[返回 NGX_DONE] 2 ) phase_handler++ji 返 





NGX_AGAIN 


3 ) 直接 返回 
NGX_OK 


4) 调用 ngx_http_finalize _request 


[返回 其 他 值 ] 





结束 请 求 并 返回 NGX_OK 


© 


图 11-9 ”ngx_http_core_rewrite_phase 方 法 的 执行 流程 





5) 如 果 handler 方 法 返回 了 第 2、 第 3、 第 4 步 中 以 外 的 返回 值 ， 则 调 


用 ngx_http_finalize_request 结 束 请 求 。ngx_http_finalize_request 方 法 中 的 


参数 就 是 handler 方 法 的 返回 值 ， 其 影响 参见 11.10.6 让 。 


当 我 们 开发 的 HTTP 模块 试图 介入 
NGX_HTTP_ POST READ PHASE.、 
NGX_HTTP PREACCESS PHASE、NGX_HTTP_LOG PHASE 这 3 个 阶 
段 处 理 请 求 时 ， 实 现 的 handler 方 法 需要 根据 上 述 步骤 决定 返回 值 。 
ngx_http_core_generic_phase 可 以 帮助 我 们 较为 简单 地 实现 强大 的 异步 无 
阻塞 处 理 能 


11.6.2 ngx_http_core_Trewrite_phase 


ngx_http_core_rewrite_phase 方 法 充当 了 用 于 重 写 URL 的 
NGX_HTTP_SERVER REWRITE_PHASE 和 和 
NGX_HTTP_REWRITE_PHASE 这 两 个 阶段 的 checker 方 法 。 图 11-9 中 描 
述 了 ngx_http_core_rewrite_phase 方 法 的 流程 ， 可 以 看 到 ， 在 调用 了 当前 
阶段 的 handler 方 法 后 ， 根 据 返 回 值 的 不 同 可 能 会 导致 3 种 结 


下 面 简要 描述 一 下 图 11-9 中 所 列 的 4 个 步 又。 


1) 首先 调用 HTTP 模 块 实现 的 handler 方 法 ， 根 据 它 的 返回 值 类 型 ， 
将 会 有 3 种 不 同 的 结果 : 返回 NGX_DECLINED 时 跳 转 到 第 2 步 执行 ， 返 
回 NGX_DONE 时 跳 转 到 第 3 步 执行 ， 返 回 其 他 值 时 跳 转 到 第 4 步 执行 。 


2) 如 果 handler 方 法 返回 NGX_DECLINED， 将 phase_handler 加 1 表 





示 将 要 执行 下 一 个 回调 方法 。 注 意 ， 此 时 返回 的 是 NGX_AGAIN， 
HTTP 框 架 不 会 把 进程 控制 权 交 还 给 epoll 事 件 框架 ， 而 是 继续 立刻 执行 
请 求 的 下 一 个 回调 方法 。 


3) 如 果 handler 方 法 返回 NGX_DONE， 则 意味 着 刚才 的 handler 方 法 
无 法 在 这 一 次 调度 中 处 理 完 这 一 个 阶段 ， 它 需要 多 次 的 调度 才能 完成 。 
注意 ， 此 时 人 返回 NGX_OK， 它 会 使 得 HTTP 框 架 立 刻 把 控制 权 交 还 给 
epoll 等 事件 模块 ， 不 再 处 理 当 前 请 求 ， 唯 有 这 个 请 求 上 的 事件 再 次 被 触 
发 时 才 会 继续 执行 。 


4) 如 果 handler 方 法 返回 除去 NGX_DECLINED 或 者 NGX_DONE 以 
外 的 其 他 值 ， 则 调用 ngx_http_finalize_request 结 束 请 求 ， 其 参数 为 
handler 方 法 的 返回 值 。 


可 以 注意 到 ，ngx_http_core_rewrite_phase 方 法 与 
ngx_http_core_generic_phase 方 法 有 一 个 显著 的 不 同 点 : 前 者 永远 不 会 导 
致 路 过 同一 个 HITP 阶 段 的 其 他 处 理 方法 ， 就 直接 跳 到 下 一 个 阶段 来 处 
理 请 求 。 原 因 其 实 很 简单 ， 可 能 有 许多 HTTP 模 块 在 
NGX_HTTP_ SERVER_REWRITE_PHASE 和 
NGX_HTTP_REWRITE_PHASE 阶 段 同时 处 理 重 写 URL 这 样 的 业务 ， 
HTTP 框 架 认为 这 两 个 阶段 的 HTTP 模 块 是 完全 平等 的 ， 序 号 靠 前 的 
HTTP 模 块 优先 级 并 不 会 更 高 ， 它 不 能 决定 序 写 徘 后 的 HTTP 模 块 是 否 


以 再 次 重 写 URL。 因 此 ，ngx_http_core_rewrite_phase 方 法 绝对 不 会 把 
phase_handler 直 接 设 置 到 下 一 个 阶段 处 理 方法 的 流程 中 ， 即 不 可 能 存在 
类 似 下 面 的 代码 。 





ngx_int_t ngx_http_core_ rewrite phase(ngx_http_request _t *r, ngx_http_phase_handler_ 





r->phase_handler = ph->next; 





11.6.3 ngx_http_core_access phase 


ngx_http_core_access_phase 方 法 是 仅 用 于 
NGX_HTTP_ACCESS_PHASE 阶 段 的 处 理 方法 ， 这 一 阶段 用 于 控制 用 户 
发 起 的 请 求 是 否 合法 ， 如 检测 客户 端的 IP 地 址 是 否 允 许 访问 。 它 涉及 
nginx.conf 配 置 文件 中 satisfy 配 置 项 的 参数 值 ， 见 表 11-2。 


表 11-2 相对 于 NGX_HTTP_ACCESS_PHASE 阶 段 处 理 方 法 ，satisfy 配 置 


项 参数 的 意义 


satisfy 的 参数 意 义 


NGX_HTTP_ACCESS_PHASE 阶段 可 能 有 很 多 HITP 模块 都 对 控制 请 求 的 访问 权限 感 兴 


CN 


ll 那么 以 哪 一 个 为 准 呢 ?” 当 satisfy 的 参数 为 al 时， 这 些 HITP ee 0 即 以 该 阶 
娄 中 全 部 的 handler 方法 共同 决定 请 求 的 访问 权限 ， 换 名 话说 ， i 段 的 所 有 handler 方法 必须 
全 部 返回 NGX_OK 才能 认为 请 求 具有 访问 权限 
与 all 相反 ， 参 数 为 any 时 意味 着 在 NGX HTTP ACCESS _ PHASE 阶段 只 要 有 任意 一 个 HITP 
模块 认为 请 求 合 法 ， 就 不 用 再 调用 其 他 HITP 模块 继续 检查 了 ， 可 以 认为 请 求 是 具有 访问 权限 
的 。 实 际 上 ， 这 时 的 情 复杂 : 如 果 其 中 任何 一 个 handler 方法 返回 NGX_OK， 则 认为 请 求 
具有 访问 权限 ; 如 果 某 一 个 handler 方 法 返回 403 或 者 401， 则 认为 请 求 没有 访问 权限 ， 还 需要 


有 点 像 “&&” 和 “||” 的 关系 


检查 NGX_HTTP _ACC A 阶段 的 其 他 handler 方法 。 也 就 是 说 ，any 配置 项 下 任何 一 个 
handler 方法 一 旦 认为 请 求 具 有 访问 权限 ， 就 认为 这 一 阶段 执行 成 功 ， 继 续 向 下 执行 ; 
个 handler 方法 认为 没有 访问 权限 ， 则 未 必 以 此 为 准 ， 还 需要 检测 其 他 的 hanlder 方法 


如 果 其 中 一 
su all 和 any 


对 于 表 11-2 的 any 配 置 项 ， 是 通过 ngx_http_request_t 结 构 体 中 的 


access_code 成 员 来 传递 handler 方 法 的 返回 值 的 ， 因 此 ， 
ngx_http_core_access_phase 方 法 会 比较 复杂 ， 如 图 11-10 所 示 。 


[检查 请 求 的 main 指 针 是 否 指 向 自己 ] 


“2 


[当前 请 求 就 是 原始 请 求 ] 


[当前 请 求 不 是 原始 请 求 ] 


1 ) 将 phase_handler 设 为 next 





2) 调 用 HTTP 模 块 实现 的 


并 返回 NGX_AGAIN 
handler 处 理 方法 并 返回 深 


[检查 handler 方 法 的 返回 值 ] 


C2 


[返回 其 他 值 ] 





[返回 NGX_AGAIN 或 者 NGX_DONE] 

















[返回 NGX_DECLINED] 
3) 直接 返回 

5) 取 出 当前 请 求 匹配 的 NGX_OK 

location 配 置 块 

[ 先 检查 location 下 satisfy 配置 项 的 值 , 再 检查 handler 方 法 的 返回 值 | 
[satisfy 配置 为 al] 

4) phase_handler ++ 

[satisfy 配 置 为 any] 并 返回 NGX_AGAIN 


[返回 NGX_ORI 





[返回 NGX_HTTP_FORBIDDEN 或 者 CS 
NGX_HTTP_UNAUTHORIZED] 


6) 将 access_code 设 置 为 
[返回 其 他 值 | handler 返 回 值 





[返回 非 NGX_OK 值 ] 


7) 将 access_code 
设置 为 0 








8) 调 用 ngx_http_finalize_request 
结束 请 求 并 返回 NCX_OK 


图 11-10 hpgx_http_cote_access_phase 方 法 的 执行 流程 


下 面 开 始 分 析 ngx_http_core_access_phase 方 法 的 流程 。 





1) 既然 NGX_HTTP_ACCESS_PHASE 阶 段 用 于 控制 客户 端 是 否 有 
权限 访问 服务 ， 那 么 它 就 不 需要 对 子 请 求 起 作用 。 如 何 判断 请 求 究 竞 是 
来 自 客户 端的 原始 请 求 还 是 被 派生 出 的 子 请 求 呢 ?很 简单 ， 检 查 
ngx_http_request_t 结 构 体 中 的 main 指 针 即 可 。 在 11.3 节 介绍 过 的 
ngx_http_init request 方法 会 把 main 指 针 指 向 其 自身 ， 而 由 这 个 请 求 派生 
出 的 其 他 子 请 求 中 的 main 指 针 ， 仍 然 会 指向 ngx_http_init request 方法 初 
始 化 的 原始 请 求 。 因 此 ， 检 查 main 成 员 与 ngx_http_request_t 自 身 的 指针 
是 否 相 等 即 可 ， 如 下 面 的 源 代码 。 











If (r != r->main) { 
r->phase_handler = ph->next; 
return NGX_AGAIN,; 

} 








如 果 当 前 请 求 只 是 一 个 派生 出 的 子 请 求 的 话 ， 是 不 需要 执行 
NGX_HTTP_ACCESS_PHASE 阶 段 的 处 理 方法 的 ， 那 么 直接 将 
phase_handler 设 为 下 一 个 阶段 《实际 上 是 
NGX_HTTP_ POST _ ACCESS_PHASE 阶 段 ) 的 处 理 方法 的 序号 。 这 时 会 
返回 NGX_AGAIN， 也 就 是 希望 HTTP 框 架 立 刻 执行 新 的 HTTP 阶 段 的 处 
地 放 2 








2) 如 果 当 前 请 求 就 是 来 自 客户 端的 原始 请 求 ， 那 么 调用 HTTP 模 块 
在 这 一 阶段 中 实现 handler 方 法 ， 它 的 返回 值 将 会 导致 出 现 3 个 分 支 : 返 
回 NGX_AGAIN 或 者 NGX_DONE 时 跳 转 到 第 3 步 执行 ， 返 回 


NGX_DECLINED 时 跳 转 到 第 4 步 执行 ， 返回 其 他 值 时 跳 转 到 第 5 步 继续 
向 下 执行 。 同 时 ， 在 第 5 步 之 后 ， 这 个 返回 值 由 于 nginx.conf 文 件 中 配置 
项 satisfy 的 参数 值 不 同 ， 也 将 具有 不 同 的 意义 。 








3) 返回 NGX_AGAIN 或 者 NGX_DONE 意 味 着 当前 的 
NGX_HTTP ACCESS_PHASE 阶 段 没 有 一 次 性 执行 完毕 ， 所 以 在 这 一 步 
中 会 暂时 结束 当前 请 求 的 处 理 ， 将 控制 权 交 还 给 事件 模块 ， 
ngx_http_core_access_phase 方 法 结束 。 当 请 求 中 对 应 的 事件 再 次 触发 时 
才 会 继续 处 理 该 请 求 。 








4) 返回 NGX_DECLINED 意 味 着 handler 方 法 执行 完毕 晶 “ 意 犹 未 
尽 ”， 和 希望 立刻 执行 下 一 个 handler 方 法 ， 无 论 其 是 否 属 于 
NGX_HTTP_ ACCESS_PHASE 阶 段 ， 在 这 一 步 中 只 需要 把 phase_handler 


加 1， 同 时 ngx_http_core_access_phase 方 法 返回 NGX_AGAIN 即 可 。 


5) 现在 开始 处 理 非 第 3、 第 4 步 中 返回 值 的 情况 。 由 于 
NGX_HTTP_ACCESS_PHASE 阶 段 是 在 
NGX_HTTP_FIND_CONFIG_PHASE 阶 段 之 后 的 ， 因 此 这 时 请 求 已 经 找 
到 了 匹配 的 location 配 置 块 ， 先 把 location 块 对 应 的 
ngx_http_core_loc_conf_t 配 置 结构 体 取 出 来 ， 因 为 这 里 有 一 个 配置 项 


satisfy 是 下 一 步 需 要 用 到 的 。 


6) 检查 ngx_http_core_loc_conf t 结 构 体 中 的 satisfy 成 员 ， 如 果 值 为 


NGX_HTTP SATISFY_ALL 〈 即 nginx.conf 文 件 中 配置 了 satisfy all 参 





数 ) ， 则 意味 着 所 有 NGX_HTTP_ACCESS_PHASE 阶 段 的 handler 方 法 必 
须 共同 作用 于 这 个 请 求 。 这 时 ，handler 方 法 的 返回 值 就 具有 不 同 的 意义 
了 。 如 果 它 的 返回 值 是 NGX_OK， 则 意味 着 这 个 handler 方 法 所 在 的 
HTTP 模 块 认为 当前 请 求 是 具备 访问 权限 的 ， 需 要 再 次 检查 
NGX_HTTP_ACCESS_PHASE 阶 段 的 下 一 个 HTTP 模 块 的 handler 方 法 ， 
于 是 会 跳 到 第 4 步 执行 ， 反 之 ， 如 有 果 返 回 值 不 是 NGX_OK， 融 意味 着 当 
前 请 求 无 权 访 问 服务 ， 这 时 需要 跳 到 第 8 步调 用 ngx_http_finalize_request 
方法 结束 请 求 ， 方 法 的 参数 也 就 是 这 个 返回 值 。 








如 果 ngx_http_core_loc_conf t 结 构 体 中 的 satisfy 成 员 值 为 
NGX_HTTP_SATISFY_ANY 〈 即 nginx.conf 文 件 中 配置 了 satisfy any 参 
数 ) ， 也 就 是 说 ， 并 不 强制 要 求 NGX_HTTP_ACCESS_PHASE 阶 段 的 所 
有 handler 方 法 必须 同时 起 作用 ， 那 么 这 时 handler 方 法 的 返回 值 又 具有 了 
不 同 的 意义 。 如 果 该 返回 值 是 NGX_OK， 则 表示 第 2 步 执行 的 handler 方 
法 认为 这 个 请 求 有 权限 访问 服务 ， 而 且 不 用 再 调用 
NGX_HTTP ACCESS_PHASE 阶 段 的 其 他 handler 方 法 了 了 ， 直 接 跳 到 第 7 





步 执 行 ， 如 果 返 回 值 是 NGX_HTTP_FORBIDDEN 或 者 

NGX_HTTP_UNAUTHORIZED， 则 表示 这 个 HTTP 模 块 的 handler 方 法 认 
为 请 求 没有 权限 访问 服务 ， 但 只 要 NGX_HTTP_ACCESS_PHASE 阶 段 的 
任何 一 个 handler 方 法 返回 NGX_OK 就 认为 请 求 合 法 ， 所 以 后 续 的 handler 
方法 可 能 会 更 改 这 一 结果 。 这 时 将 请 求 的 access_code 成 员 设置 为 handler 


方法 的 返回 值 ， 用 于 传递 当前 HTTP 模 块 的 处 理 结 果 ， 然 后 跳 到 第 4 步 执 
行 下 一 个 handler 方 法 ， 如 果 返 回 值 为 其 他 值 ， 可 以 认为 请 求 绝对 无 权 访 
问 服 务 ， 则 跳 到 第 8 步 执 行 。 


7) 上 面 已 经 解释 过 ， 在 satisfy any 配 置 下 ，handler 方 法 返回 
NGX_OK 时 意味 着 这 个 请 求 具 备 访问 权限 ， 将 请 求 的 access_code 成 员 置 
为 0， 跳 到 第 1 步 执行 。 


8) 调用 ngx_http_finalize_request 方 法 结束 请 求 。 


虽然 ngx_http_core_access_phase 方 法 有 些 复杂 ， 即 它 为 
NGX_HTTP_ACCESS_PHASE 阶 段 中 的 handler 方 法 的 返回 值 增 加 了 过 多 
的 含义 ， 但 当 我 们 开发 的 HTTP 模 块 需要 处 理 请 求 的 访问 权限 时 ， 就 会 
发 现 ngx_http_core_access_phase 方 法 给 我 们 带 来 强大 的 功能 ， 可 以 实现 
复杂 的 权限 控制 。 


11.6.4 ngx_http_core_content phase 


ngx_http_core_content_phase 是 NGX_HTTP_CONTENT_PHASE 阶 段 
的 checker 方 法 ， 可 以 说 它 是 我 们 开发 HTTP 模 块 时 最 常用 的 一 个 阶段 
了 。 顾 名 思 义 ，NGX_HTTP_CONTENT_PHASE 阶 段 用 于 真正 处 理 请 求 
的 内 容 。 其 余 10 个 阶段 中 各 HTTP 模 块 的 处 理 方法 都 是 放 在 全 局 的 
ngx_http_core_main_conf t 结 构 体 中 的 ， 也 就 是 说 ， 它 们 对 任何 一 个 


HTTP 请 求 都 是 有 效 的 。 但 在 NGX_HTTP_CONTENT_ PHASE 阶段 却 很 
自然 地 有 男 一 种 需求 ， 有 的 HTTP 模 块 可 能 仅 希 望 在 这 个 处 理 请 求 内 容 
的 阶段 ， 仅 仅 针 对 某 种 请 求 唯一 生效 ， 而 不 是 对 所 有 请 求生 效 。 例 如 ， 
仅 当 请 求 的 URI 匹 配 了 配置 文件 中 的 菏 个 location 块 时 ， 再 根据 location 块 
下 的 配置 选择 一 个 HTTP 模 块 执行 它 的 handler 处 理 方法 ， 并 以 此 替代 
NGX_HTTP_CONTENT_PHASE 阶 段 的 其 他 handler 方 法 (这 些 handler 方 
法 对 于 该 请 求 将 得 不 到 执行 ) 。 





既然 我 们 希望 请 求 在 NGX_HTTP_CONTENT PHASE 阶段 的 handler 
方法 仅 与 Jocation 相 关 ， 那 么 就 衣 定 与 ngx_http_core_loc_conf t 结 构 体 相 
关 了 ， 注 意 handler 成 员 : 








struct ngx_http_core_ loc conf_s { 


ngx_http_handler_pt handler,; 





这 个 handler 成 员 属于 nginx.conf 中 匹配 了 请 求 的 location 块 下 配置 的 
HTTP 模 块 〈 当 然 ， 如 果 请 求 匹配 的 location 块 下 没有 配置 HTTP 模块 处 
理 请 求 ， 那 么 这 个 handler 指 针 将 为 NULL 空 指针 ) 。 回 顾 一 下 第 3 章 中 的 
ngx_http_mytest 方 法 ， 它 正 是 在 某 个 location 下 检测 到 mytest 配 置 项 后 ， 


取 到 当前 location 下 的 ngx_http_core_loc_conf t 结 构 体 ， 并 把 handler 成 员 
设置 为 希望 在 NGX_HTTP_CONTENT_PHASE 阶 段 处 理 请 求 的 


ngx_http_mytest_handler 方 法 的 。 


实际 上 ， 为 了 加 快 处 理 速度 ，HTTP 框 架 义 在 ngx_http_request_t 结 
构 体 中 增加 了 一 个 成 员 content_handler (参见 11.3.1 节 )〉) ， 在 
NGX_HTTP_FIND_CONFIG_PHASE 阶 段 就 会 把 它 设 为 匹配 了 请 求 URI 
的 location 块 中 对 应 的 ngx_http_core_loc_conf_t 结 构 体 的 handler 成 员 〈 参 
见 Nginx 源 代码 的 ngx_http_update_location_config 方 法 ) 。 


以 上 所 述 是 NGX_HTTP_CONTENT_PHASE 阶 段 的 特殊 之 处 ， 当 
然 ， 它 还 可 以 像 其 余 10 个 阶段 一 样 具 备 全 局 生效 的 handler 方 法 ， 但 如 果 
设置 了 content_handler 方 法 ， 会 优先 以 content_handler 为 准 ， 如 图 11-11 
所 示 。 


下 面 详细 介绍 一 下 ngx_http_core_content_phase 方 法 是 如 何 处 理 
NGX_HTTP CONTENT _ PHASE 阶段 的 请 求 的 。 


1) 首先 检测 ngx_http_request_t 结 构 体 的 content_handler 成 员 是 否 为 
空 ， 其 实 就 是 看 在 NGX_HTTP_FIND_CONFIG_PHASE 阶 段 匹 配 了 URI 
请 求 的 location 内 ， 是 否 有 HTTP 模 块 把 处 理 方法 设置 到 了 
ngx_http_core_loc_conf _t 结 构 体 的 handler 成 员 中 。 如 果 content_handler 为 
空 ， 则 跳 到 第 2 步 开 始 执行 全 局 有 效 的 handler 方 法 ;否则 仅 执行 





content_handler 方 法 ， 看 看 源 代码 中 做 了 些 什 么 ， 如 下 所 示 。 





r->write event_handler = ngx_http_request_ empty_handler; 
ngx_http_finalize_request(r, r->content_handler(r)); 





其 中 ， 首 先 设 置 ngx_http_request_t 结 构 体 的 write_event_handler 成 员 
为 不 做 任何 事 的 ngx_http_request_empty_handler 方 法 ， 也 就 是 告诉 HTTP 
框架 再 有 可 写 事件 时 就 调用 ngx_http_request_empty_handler 直 接 把 控制 
权 交 还 给 事件 模块 。 为 何 要 这 样 做 呢 ? 因为 HITP 框 架 在 这 一 阶段 调用 
HTTP 模 块 处 理 请 求 就 意味 着 接 下 来 只 希望 该 模块 处 理 请 求 ， 先 把 
write_event_handler 强 制 转化 为 ngx_http_request_empty_handler， 可 以 防 
止 该 HTTP 模 块 异步 地 处 理 请 求 时 却 有 其 他 HTTP 模 块 还 在 同时 处 理 可 写 
事件 、 向 客户 端 发 送 响应 。 接 下 来 调用 content_handler 方 法 处 理 请 求 ， 
并 把 它 的 返回 值 作为 参数 传递 给 ngx_http_finalize_request 方 法 来 结束 请 
求 。ngx_http_finalize_request 方 法 是 非常 复杂 的 ， 它 会 根据 引用 计数 来 
确定 目 己 的 行为 ， 具体 参见 11.10.6 市 。 




















2) 在 没有 content_handler 方 法 时 ， 又 回 到 了 我 们 惯用 的 方式 ， 首 先 
根据 phase_handler 序 号 调用 handler 处 理 方法 ， 检 测 它 的 返回 值 : 当 返 回 
值 为 NGX_DECLINED 时 跳 到 第 4 步 ， 人 否则 跳 到 第 3 步 执行 。 


3) 如 果 NGX_HTTP_ CONTENT PHASE 阶段 中 全 局 的 handler 方 法 
没有 返回 NGX_DECLINED， 则 意味 着 不 再 执行 该 阶段 的 其 他 handler 方 
法 。 因 此 ， 这 时 简单 地 以 handler 方 法 作为 参数 调用 


ngx_http_finalize request 结束 请求 即 可 。 同 时 ， 





ngx_http_core_content_phase 方 法 返回 NGX_OK， 表 示 归 还 控制 权 给 事件 
模块 。 


[检查 匹配 了 请 求 eo content_handle 芒 法 | 


* 


[不 存在 content_handle 访 法 | 


[存在 content_handler 方 法 |] 


1 ) 调用 content_handler 


方法 并 结束 请 求 





2) 调用 HTTP 模 块 实现 的 


handler 处 理 方法 
[检查 handle 访 法 的 返回 值 ] 


<> 


[返回 NGX_DECLINED] 3) 调用 ngx_http_finalize _request 
结束 请 求 





[返回 值 不 是 NGX_DECLINED] 





4 ) 转 到 下 一 个 





ngx_http_phase_handler_t 处 理 方法 
[检查 ngx_http_phase_handlert 的 checker 是 否 实现 ] 


> [checker 方 法 存在 ] 


[cehecker 方 法 不 存在 ,检查 请 求 的 URH] 5) phase_handler++ 并 返回 


NGX_AGAIN 





[请 求 的 URI 以 /结尾 ] 








6) 调用 ngx_http_finalize _request 
结束 请 求 ， 返 回 403 


7) 调 用 ngx_http_finalize _request 
结束 请 求 ， 返 回 404 


@ 


图 11-11 ngx_http_core_content_phase 方 法 的 流程 


4) 虽然 handler 方 法 返回 了 NGX_DECLINED， 表 示 希 望 执行 本 阶段 
的 下 一 个 handler 方 法 ， 但 是 当前 的 handler 方 法 是 否 已 经 是 最 后 一 个 








handler 方 法 了 呢 ? 这 需要 进行 检测 ， 首 先 转 到 数组 中 的 下 一 个 handler 方 
法 ， 检 测 其 checker 方 法 是 否 存 在 ， 奉 存在 ， 则 跳 到 第 5 步 执 行 ， 硝 不 存 
在 ， 则 结束 请 求 ， 但 需要 根据 URI 确 定 返回 什么 样 的 HTTP 响应， 如 果 
URI 是 以 “/ 结 尾 ， 则 跳 到 第 6 步 执行 ， 人 否则 跳 到 第 7 步 执 行 。 





5) 既然 handler 方 法 返回 NGX_DECLINED 和 希望 执行 下 一 个 handler 方 
法 ， 那 么 这 一 步 把 请 求 的 phase_handler 序 号 加 1， 
ngx_http_core_content_phase 方 法 返回 NGX_AGAIN， 表 示 希 望 HTTP 框 
染 了 立刻 执行 下 一 个 handler 方 法 。 


6) 以 NGX_HTTP_FORBIDDEN 作 为 参数 调用 
ngx_http_finalize_request 方 法 ， 表 示 结 束 请 求 并 返回 403 错 误 码 。 同 时 ， 
ngx_http_core_content_phase 方 法 返回 NGX_OK， 表 示 交 还 控制 权 给 事件 
模块 。 





7) 以 NGX_HTTP_NOT_FOUND 作 为 参数 调用 
ngx_http_finalize_request 方 法 ， 表 示 结 束 请 求 并 返回 404 错 误 码 。 同 时 ， 
ngx_http_core_content_phase 方 法 返回 NGX_OK， 表 示 交 还 控制 权 给 事件 
模块 。 





NGX_HTTP_ CONTENT _ PHASE 阶段 是 各 HTTP 模 块 最 常 介入 的 阶 
段 。 只 有 对 ngx_http_core_content_phase 方 法 的 流程 足够 熟悉 ， 才 能 实现 
复杂 的 功能 。 


@ 注意 ”从 ngx_http_core_content_phase 方 法 中 可 以 看 到 ， 请 求 在 
第 10 个 阶段 NGX_HTTP_CONTENT_PHASE 后 ， 并 没有 去 调用 第 11 个 阶 
段 NGX_HTTIP LOG_PHASE 的 处 理 方 法 ， 通 过 比较 11.6 节 的 其 他 checket 
方法 ， 就 会 发 现 它 与 之 前 的 方法 都 不 同 。 事 实 上 ， 记 录 访 问 日 志 是 必须 
在 请 求 将 要 结束 时 才能 进行 的 ， 因 此 ，NGX_HTTP LOG_PHASE 阶 段 


的 回调 方法 在 11.10.2 节 介绍 的 nex_http_ftee_tequest 方 法 中 才 会 调用 到 。 


11.7 ”subrequest 与 post 请 求 





从 11.6 节 中 可 以 看 到 ，HTTP 框 架 无 论 是 调用 
ngX_http_process_request 方 法 《〈 首 次 从 业务 上 处 理 请 求 ) 还 是 
ngx_http_request_handler 方 法 〈TCP 连 接 上 后 续 的 事件 触发 时 ) 处 理 请 
求 ， 最 后 都 有 一 个 步 又， 就 是 调用 ngx_http_run_posted_requests 方 法 处 
理 post 请 求 〈 如 图 11-5 中 的 第 8 步 、 图 11-7 中 的 第 4 步 ) 。 那 么 ， 什 么 是 
post 请 求 ? 为 什么 要 定义 post 请 求 ? post 请 求 又 是 怎样 实现 于 HTTP 框 架 


中 的 呢 ? 本 市 内 容 将 回答 这 3 个 问题 。 














Nginx 使 用 的 完全 无 阻塞 的 事件 驱动 框架 是 难以 编写 功能 复杂 的 模 
块 的 ， 可 以 想见 ， 一 个 请 求 在 处 理 一 个 TCP 连 接 时 ， 将 需要 处 理 这 个 连 
接 上 的 可 读 、 可 写 以 及 定时 器 事件 ， 而 可 读 事件 中 又 包含 连接 建立 成 
功 、 连 接 关 闭 事件 ， 正 常 的 可 读 事 件 在 接收 到 HTTP 的 不 同 部 分 时 又 要 
做 不 同 的 处 理 ， 这 就 比较 复杂 了 。 如 果 一 个 请 求 同 时 需要 与 多 个 上 游 服 
务 器 打交道 ， 同 时 处 理 多 个 TCP 连 接 ， 那 么 它 需 要 处 理 的 事件 就 太 多 
了 ， 这 种 复杂 度 会 使 得 模块 难以 维护 。Nginx 解 决 这 个 问题 的 手段 就 是 
第 5 章 中 介绍 过 的 subrequest 机 制 。 














subrequest 机 制 有 以 下 两 个 特点 : 


. 从 业务 上 把 一 个 复杂 的 请 求 拆 分 成 多 个 子 请 求 ， 由 这 些 子 请 求 共 


同 合作 完成 实际 的 用 户 请 求 。 


- 每 一 个 HTTP 模 块 通常 只 需要 关心 一 个 请 求 ， 而 不 用 试图 掌握 派 
生出 的 所 有 子 请 求 ， 这 极 大 地 降低 了 模块 的 开发 复杂 度 。 


这 两 个 特点 使 得 用 户 可 以 通过 开发 多 个 功能 相对 单一 独立 的 模块 ， 
来 共同 完成 复杂 的 业务 。 


post 请 求 的 设计 就 是 用 于 实现 subrequest 子 请 求 机 制 的 ， 如 果 一 个 请 
求 具 备 了 post 请 求 ， 并 且 HTTP 框 架 保 证 post 请 求 可 以 在 当前 请 求 执行 完 
毕 后 获得 执行 机 会 ， 那 么 subrequest 功 能 就 可 以 实现 了 。 子 请 求 的 设计 
在 数据 结构 上 是 通过 ngx_http_request_t 结 构 体 的 3 个 成 员 
《posted_requests、parent、main) 来 保证 的 。 下 面 看 一 下 表示 单 同 链表 
的 posted_requests 成 员 ， 它 的 类 型 是 ngx_http_posted_request_t 结 构 体 ， 


如 下 所 示 。 

















typedef struct ngx_http_posted request s ngx_http_posted request tt， 
struct ngx_http_posted request s { 
// 指向 当前 待 处 理子 请 求 的 





ngx_http_request_t 结 构 体 


ngx_http_request_t *request,; 
// 指向 下 一 个 子 请 求 ， 如 果 没 有 ， 则 为 


NULL 空 指针 
ngx_http_posted_ request_t *next; 


了 


一 


这 样 ， 通 过 posted_requests 束 把 各 个 子 请 求 以 单 同 链表 的 数据 结构 
形式 组 织 起 来 了 。 


ngx_http_request_t 结 构 体 中 的 parent 指 向 了 当前 子 请 求 的 父 请 求 ， 
这 为 子 请 求 同 前 寻找 父 请 求 提供 了 可 能 性 。 


ngx_http_request_t 结 构 体 中 的 main 成 员 始 终 指向 一 系列 有 亲缘 关系 
的 请 求 中 的 唯一 的 那个 原始 请 求 。 我 们 可 以 在 任何 一 个 子 请 求 中 通过 
main 成 员 找 到 原始 请 求 ， 而 无 论 怎样 执行 子 请 求 ， 都 是 围绕 着 main 指 问 
的 原始 请 求 进行 的 ， 在 图 11-12 中 可 以 看 到 。 





[检查 Nginx Dp 户 靖 的 连接 | 


[与 客户 端的 TCP 连 接 存 在 ] 


[TCP 连 接 已 销毁 ] 


1 ) 获取 原始 请 求 posted_requests 


链表 的 首 个 post 请 求 
| 检 查 post 语 求 是 盏 存 在 | 





| post 请 求 不 存 在 | 
| 具有 post 请 求 | 


原 始 请 求 的 posted_requests 
| 


3 ) 执 行当 前 post 请 求 的 
write_event_handle 芒 法 





图 11-12 ” post 请 求 的 执行 


ngx_http_request_t 结 构 体 中 的 count 成 员 将 作为 引用 计数 ， 每 当 派 生 
出 子 请 求 时 ， 原 始 请 求 的 count 成 员 都 会 加 1， 在 真正 销毁 请 求 前 ， 可 以 
通过 检查 count 成 员 是 否 为 0 以 确认 是 否 销毁 原始 请 求 ， 这 样 可 以 做 到 唯 
有 上 所 有 的 子 请 求 都 结束 时 ， 原 始 请 求 才 会 销毁 ， 内 存 池 、TCP 连 接 等 资 
源 才 会 释放 。 


对 于 subrequest 子 请 求 的 用 法 ， 可 参见 5.4 节 ， 这 里 不 再 痪 述 。 图 11- 


12 展 示 ngx_http_run_posted_requests 方 法 是 怎么 执行 一 个 请 求 的 post 请 求 


的 ， 也 就 是 如 果 一 个 请 求 拥 有 子 请 求 时 ， 子 请 求 是 怎么 被 调度 的 。 


从 图 11-12 中 可 以 看 到 ， 在 执行 某 一 个 请 求 时 ， 它 的 所 有 post 请 求 都 
可 能 被 执行 一 过 。 下 面 详细 介绍 以 上 流程 。 





1) 首先 检查 连接 是 否 已 销毁 ， 如 果 连 接 被 销毁 ， 就 结束 
ngx_http_run_posted_requests 方 法 ， 人 否则 根据 ngx_http_request_t 结 构 体 中 
的 main 成 员 找 到 原始 请 求 ， 这 个 原始 请 求 的 posted_requests 成 员 指 问 待 
处 理 的 post 请 求 组 成 的 单 链 表 ， 如 果 posted_requests 指 向 NULL 空 指针 ， 
则 结束 ngx_http_run_posted_requests 方 法 ， 和 否则 取出 链表 中 首 个 指 同 post 
请 求 的 指针 ， 并 跳 到 第 2 步 执行 。 


2) 将 原始 请 求 的 posted_requests 指 针 指 回 链表 中 下 一 个 post 请 求 
(通过 第 1 个 post 请 求 的 next 指 针 可 以 获得 ) ， 当 然 ， 下 一 个 post 请 求 有 
可 能 不 存在 ， 这 在 下 一 次 循环 中 就 会 检测 到 。 





3) 调用 这 个 post 请 求 ngx_http_request_t 结 构 体 中 的 
write_event_handler 方 法 。 为 什么 不 是 执行 read_event_handler 方 法 呢 ? 原 
因 很 简单 ， 子 请 求 不 是 被 网 络 事件 驱动 的 ， 因 此 ， 执 行 post 请 求 时 就 相 
当 于 有 可 写 事 件 ， 由 Nginx 主 动 做 出 动作 。 








在 本 节 可 以 看 到 ，HTTP 框 架 在 处 理 一 个 请 求 时 ， 如 果 发 现 其 有 子 
请 求 则 一 定 会 处 理 。 通 过 修改 原始 请 求 的 posted_requests 指 针 ， 甚 至 还 
可 以 控制 从 哪 一 个 子 请 求 开 始 执 行 ， 当 然 ， 直 接 修改 HTTP 框 架 中 的 成 


11.8 处理 HTTP 包 体 





本 节 开 始 介绍 HTTP 框 架 为 HTTP 模块 提供 的 工具 方法 。 在 HTTP 
中 ， 一 个 请 求 通常 由 必 选 的 HTTP 请 求 行 、 请 求 头 部 ， 以 及 可 选 的 包 体 
组 成 ， 因 此 ， 在 接收 完 HITP 头 部 后 ， 就 可 以 开始 调用 各 HTTP 模 块 处 理 
请 求 了 《〈 见 11.6 节 ) ， 然 后 由 HTTP 模块 决定 如 何 处 理 包 体 。 





HTTP 框 架 提 供 了 两 种 方式 处 理 HTTP 包 体 ， 当 然 ， 这 两 种 方式 保持 
了 完全 无 阻塞 的 事件 驱动 机 制 ， 非 常 高 效 。 第 一 种 方式 就 是 把 请 求 中 的 
包 体 接收 到 内 存 或 者 文件 中 ， 当 然 ， 由 于 包 体 的 长 度 是 可 变 的 ， 同 时 内 
存 又 是 有 限 的 ， 因 此 ， 一 般 都 是 将 包 体 存 放 到 文件 中 《本 节 不 会 详细 讨 
论 包 体 的 存储 策略 ) 。 第 二 种 方式 是 选择 丢弃 包 体 ， 注 意 ， 丢 大 不 等 于 
可 以 不 接收 包 体 ， 这 样 做 可 能 会 导致 客户 端 出 现 发 送 请 求 超时 的 错误 ， 
所 以 ， 这 个 丢弃 只 是 对 于 HTTP 模 块 而 言 的 ，HTTP 框 架 还 是 需要 “尽职 
尽责 ”地 接收 包 体 ， 在 接收 后 直接 丢弃 。 











本 节 将 会 遇 到 一 个 问题 ， 这 个 问题 需要 用 请 求 ngx_http_request_t 结 
构 体 中 的 count 引 用 计数 解决 。 举 个 例子 ，HTTP 模 块 在 处 理 请 求 时 ， 接 
收 包 体 的 同时 可 能 还 需要 处 理 其 他 业务 ， 如 使 用 upstream 机 制 与 另 一 台 
服务 器 通信 ， 这 样 两 个 动作 都 不 是 一 次 调度 可 以 完成 的 ， 它 们 各 自 都 可 
能 需要 多 次 调度 才能 完成 ， 那 么 在 其 中 一 个 动作 出 现 错误 导致 请 求 失 败 





时 ， 如 果 销 毁 请 求 可 能 会 导致 万 一 个 动作 出 现 严 重 错误 ， 怎 么 办 ? 这 时 
就 需要 用 到 引用 计数 了 。 


在 HTTP 模 块 中 每 进行 一 类 新 的 操作 ， 包 括 为 一 个 请 求 添加 新 的 事 
件 ， 或 者 把 一 些 已 经 由 定时 器 、epoll 中 移 除 的 事件 重新 加 入 其 中 ， 都 需 
要 把 这 个 请 求 的 引用 计数 加 1。 这 是 因为 需要 让 HTTP 框 架 知 道 ，HTTP 
模块 对 于 该 请 求 有 独立 的 异步 处 理 机 制 ， 将 由 该 HTTP 模 块 决定 这 个 操 
作 什 么 时 候 结 束 ， 防 止 在 这 个 操作 还 未 结束 时 HTTP 框 架 却 把 这 个 请 求 
销毁 了 《如 其 他 HTTP 模 块 通过 调用 ngx_http_finalize_request 方 法 要 求 
HTTP 框 架 结 束 请 求 ) ， 导 致 请 求 出 现 不 可 知 的 严重 错误 。 这 就 要 求 每 
个 操作 在 “认为 ”自身 的 动作 结束 时 ， 都 得 最 终 调用 到 
ngx_http_close_request 方 法 ， 该 方法 会 自动 检查 引用 计数 ， 当 引用 计数 
为 0 时 才 真 正 地 销毁 请 求 。 实 际 上 ， 很 多 结束 请 求 的 方法 最 后 一 定 会 调 
用 到 ngx_http_close_request 方 法 〈 参 见 11.10.3 节 ) 。 











由 于 HTTP 包 体 是 可 变 长 度 的 ， 接 收 包 体 可 能 导致 HTTP 框架 将 TCP 
连接 上 的 读 事件 再 次 添加 到 epol 和 定时 志 中 ， 表 示 和 希望 事件 驱动 机 制 发 
现 TCP 连 接 上 接收 到 全 部 或 者 部 分 HITP 包 体 时 ， 回 调 相应 的 方法 读 取 
套 接 字 绥 冲 区 上 的 TCP 流 ， 这 时 必须 把 请 求 的 引用 计数 加 1， 这 在 图 11- 
13 的 第 1 步 中 就 可 以 看 到 。 类 似 的 ， 在 第 5 章 介绍 的 subrequest 子 请 求 的 
使 用 方法 中 ， 派 生子 请 求 也 是 独立 的 动作 ， 它 会 同 epoll 和 定时 器 中 添加 
新 的 事件 ， 引 用 计数 也 会 加 1， 而 upstream 试 图 连接 新 的 服务 器 ， 它 同样 








也 需要 把 当前 请 求 的 引用 计数 加 1。 当 这 类 操作 结束 时 ， 如 HTTP 包 体 全 
部 接收 完毕 时 ， 务 必 调 用 或 者 间接 地 调用 ngx_http_close_request 方 法 ， 
把 引用 计数 减 1， 这 才能 使 引用 计数 机 制 正常 工作 。 


@@ 注意 引用 计数 一 般 都 作用 于 这 个 请 求 的 原始 请 求 上 ， 因 此 ， 
在 结束 请 求 时 统一 检查 原始 请 求 的 引用 计数 就 可 以 了 。 当 然 ， 目 前 的 
HTTP 框 架 也 要 求 我 们 必须 这 样 做 ， 因 为 ngx_http_close_request 方 法 只 是 
把 原始 请 求 上 的 引用 计数 减 1。 对 应 到 代码 就 是 操作 f->main->count 成 


员 ， 其 中 t 是 请 求 对 应 的 ngx_http_request_t 结 构 体 。 


下 面 来 看 看 HTTP 框 染 提 供 的 方法 是 如 何 使 用 的 ， 接 收 包 体 的 方法 
其 实在 3.6.4 节 中 已 经 讲 过 ， 再 来 回顾 一 下 。 





ngx_int_t ngx_http_read client request body(ngx_http_request _t *r，ngx_http_client 








调用 了 ngx_http_read_client_request_body 方 法 就 相当 于 启动 了 接收 
包 体 这 一 动作 ， 在 这 个 动作 完成 后 ， 束 会 回调 HTTP 模 块 定义 的 
post_handler 方 法 。post_handler 是 一 个 函数 指针 ， 如 下 所 示 。 





typedef void (*ngx_http_client body_handler_pt) (ngx_http_request t *r); 








而 决定 丢弃 包 体 时 ，HTTP 框 架 提供 的 方法 是 
ngx_http_discard_request_body， 如 下 所 示 。 





ngx_int_t ngx_http_discard_request_body(ngx_http_redquest_t *r) 








当然 ， 它 是 不 需要 再 让 HTTP 模 块 定义 类 似 post_handler 的 回调 方法 
的 ， 当 丢弃 包 体 后 ，HTTP 框 架 会 自动 调用 ngx_http_finalize_request 方 法 
把 引用 计数 减 1， 详 见 11.8.2 节 。 


在 11.8.1 节 中 将 会 讨论 HTTP 框 架 是 怎样 实现 
ngX_http_read_client_ request_ body 方法 的 ， 而 在 11.8.2 节 中 则 会 讨论 
ngx_http_discard_request_body 方 法 的 实现 ， 由 于 这 两 个 方法 都 需要 被 事 
件 框架 多 次 调度 ， 学 习 它 们 的 设计 方法 可 以 帮助 我 们 开发 高 效 的 Nginx 
模块 。 


11.8.1 接收 包 体 


在 讨论 ngx_http_read_client_request_body 方 法 的 实现 方式 前 ， 先 来 
看 一 下 用 于 保存 HTTP 包 体 的 结构 体 ngx_http_request_body_t， 如 下 所 


帮 \。 





typedef struct { 
// 存放 


HTTP 包 体 的 临时 文件 


ngx_temp_file t *temp_file; 
/接收 


HTTP 包 体 的 缓冲 区 链表 。 当 包 体 需 要 全 部 存放 在 内 存 中 时 ， 如 果 一 块 


ngx_buf t+ 缓冲 区 无 法 存放 完 ， 这 时 就 需要 使 用 


ngx_chain_t 链 表 来 存放 


WA 
ngx_chain_t *bufs; 
// 直接 接收 


HTTP 包 体 的 缓存 


ngx_buf_t *buf; 
/* 根 据 


content-length 头 部 和 已 接收 到 的 包 体 长 度 ， 计 算出 的 还 需要 接收 的 包 体 长 度 


*/ 
off_t rest; 
// 该 缓冲 区 链表 存放 着 将 要 写 入 文件 的 包 体 


ngx_chain_t *to_write,; 
A/*HTTP 包 体 接收 完毕 后 执行 的 回调 方法 ， 也 就 是 


ngx_http_read_client_request_body 方 法 传递 的 第 





2 个 参数 


* 
/ 
ngx_http_client_body_handler_pt post_handler; 
} ngx_http_request body_t; 











这 个 ngx_http_request_body_t 结 构 体 束 存 放 在 保存 着 请 求 的 
ngx_http_request_t 结 构 体 的 request_body 成 员 中 ， 接 收 HTTP 包 体 就 是 
绕 着 这 个 数据 结构 进行 的 。 


上 上 文 说 过 ， 在 接收 较 大 的 包 体 时 ， 无 法 在 一 次 调度 中 完成 。 通 俗 地 
讲 ， 就 是 接收 包 体 不 是 调用 一 次 ngx_http_read_client_request_body 方 法 


就 能 完成 的 。 但 是 HITP 框 架 希 望 对 于 它 的 用 户 ， 也 就 是 HITP 模 块 而 
言 ， 接 收 包 体 时 只 需要 调用 一 次 ngx_http_read_client_request_body 方 法 
就 好 ， 这 时 就 需要 有 另 一 个 方法 在 ngx_http_read_client_request_body 没 
接收 到 完整 的 包 体 时 ， 如 果 连 接 上 再 次 接收 到 包 体 就 被 调用 ， 这 个 方法 


了 驶 是 ngx_http_read_client_request_body_handler。 





ngx_http_read_client request_body_handler 方 法 对 于 HTTP 模 块 是 不 
可 见 的 ， 它 在 “ 疾 后 ?工作 。 当 继续 接收 发 目 客 户 端 的 包 体 时 ， 将 由 它 来 
处 理 。 可 见 ， 它 与 ngx_http_read_client_ request body 方法 有 很 多 共通 之 
处 ， 它 们 都 会 去 试图 读 取 连接 套 接 字 上 的 缓冲 区 ， 把 它们 共性 的 部 分 提 
取出 来 构成 ngx_http_do_read_client_request_body 方 法 ， 它 负责 具体 的 读 
取 包 体 工作 。 本 节 的 内 容 就 在 于 说 明 这 3 个 方法 的 流程 。 








图 11-13 为 ngx_http_read_client_request_body 方 法 的 流程 图 ， 在 该 图 
中 同时 可 以 看 到 ngx_http_request_t 结 构 体 中 的 request_body 成 员 是 如 何 分 
配 和 使 用 的 。 






1) 原始 请 求 的 引用 计数 加 1 


3 ) 分 配 用 于 接收 包 体 的 
request_body 成 员 


[检查 请 求 的 otent: length 头 部 ] 


[已 经 做 过 放弃 包 体 或 者 接收 包 体 的 操作 ] 





[content_length 小 于 或 等 于 0] 





[content Jength 大 于 0] 


4) 设置 接收 完全 部 包 体 后 的 





post_handler 回 调 方法 
[检查 已 经 读 取 到 的 包 体 长 度 ] 


[已 接收 到 的 包 体 长 度 大 于 或 等 于 content_length] 





[还 没有 接收 到 全 部 的 包 体 , 检查 jieaderin 缓冲 区 是 否 可 接收 全 部 包 体 ] 








[headerin 绥 冲 区 无 法 存放 全 部 包 体 ] 


2 ) 调 用 HTTP 模 块 要 求 回调 的 





[接收 头 部 的 header_in 组 冲 区 可 以 存放 完整 的 包 体 ] post_handler 方 法 










5 ) 在 request_body 
上 分 配 用 于 接收 包 体 的 缓冲 区 







6) 设置 后 续 接收 连接 上 TCP 流 的 


read_event_handler 方 








7 ) 调用 ngx_do_read_client_request_body 


方法 接收 包 体 





外 


图 11-13 ngx_http_tead_client_tequest body 方法 的 流程 图 


图 11-13 把 ngx_http_read_client_request_body 方 法 的 主要 流程 概括 为 
7 个 步骤 ， 下 面 详细 说 明 一 下 。 


1) 首先 把 该 请 求 对 应 的 原始 请 求 的 引用 计数 加 1。 这 同时 是 在 要 求 
每 一 个 HTTP 模块 在 传 入 的 post_handler 方 法 被 回调 时 ， 务 必 调 用 类 似 
ngx_http_finalize_request 的 方法 去 线束 请 求 ， 人 否则 引用 计数 会 始终 无 法 
清 零 ， 从 而 导致 请 求 无 法 释放 。 


检查 请 求 ngx_http_request_t 结 构 体 中 的 request_body 成 员 ， 如 果 它 已 
经 被 分 配 过 了 ， 证 明 已 经 读 取 过 HTTP 包 体 了 ， 不 需要 再 次 读 取 一 遍 ， 
这 时 跳 到 第 2 步 执行 ， 再 检查 请 求 ngx_http_request_t 结 构 体 中 的 
discard_body 标 志 位 ， 如 果 discard_body 为 1， 则 证 明 曾 经 执行 过 丢弃 包 
体 的 方法 ， 现 在 包 体 正 在 被 丢弃 中 ， 仍 然 跳 到 第 2 步 执行 。 只 有 这 两 个 
条 件 都 不 满足 ， 才 说 明 真正 需要 接收 HTTP 包 体 ， 这 时 跳 到 第 3 步 执行 。 





2) 这 一 步 将 直接 执行 各 HTTP 模 块 提供 的 post_handler 回 调 方法 ， 接 
着 ，ngx_http_read_client_request_body 方 法 返回 NGX_OK。 


3) 分 配 请 求 的 ngx_http_request_t 结 构 体 中 的 request_body 成 员 (之 
前 request_body 是 NULL 空 指针 ) ， 准 备 接 收 包 体 。 


4) 检 碍 请 求 的 content-length 头 部 ， 如 果 指 定 了 包 体 长 度 的 content- 
length 字 段 小 于 或 等 于 0， 当 然 不 用 继续 接收 包 体 ， 跳 到 第 2 步 执行 ， 如 
果 content-length 大 于 0， 则 意味 着 继续 执行 ， 但 HTTP 模 块 定义 的 
post_handler 方 法 不 会 知道 在 哪 一 次 事件 的 触发 中 会 被 回调 ， 所 以 先 把 它 
设置 到 request_body 结 构 体 的 post_handler 成 员 中 。 














5) 注意 ， 在 11.5 节 描述 的 接收 HTTP 头 部 的 流程 中 ， 是 有 可 能 接收 
到 HTTP 包 体 的 。 首 先 我 们 需要 检查 在 header_in 绥 冲 区 中 已 经 接收 到 的 
包 体 长 度 ， 确 定 其 是 否 大 于 或 者 等 于 content-length 头 部 指定 的 长 度 ， 如 
果 大 于 或 等 于 则 说 明 已 经 接收 到 完整 的 包 体 ， 这 时 跳 到 第 2 步 执行 。 


当 上 述 条 件 不 满足 时 ， 再 检查 header_in 绥 冲 区 里 的 剩余 空闲 空间 是 
否 可 以 存放 下 全 部 的 包 体 (content-length 头 部 指定 ) ， 如 果 可 以 ， 就 不 
用 分 配 新 的 包 体 绥 冲 区 浪费 内 存 了 ， 和 直接 跳 到 第 6 步 执行 。 


当 以 上 两 个 条 件 都 不 满足 时 ， 说 明确 实 需要 分 配 用 于 接收 包 体 的 组 
冲 区 了 。 组 冲 区 长 度 由 nginx.conf 文 件 中 的 client body_buffer size 配置 项 
指定 ， 绥 冲 区 就 在 ngx_http_request_body_t 结 构 体 的 buf 成 员 中 存放 着 ， 
同时 ，bufs 和 to_write 这 两 个 缓冲 区 链表 首部 也 指向 该 buf。 








6) 设置 请 求 ngx_http_request_t 结 构 体 的 read_event_handler 成 员 为 上 
面 介 绍 过 的 ngx_http_read_client_request_body_handler 方 法 ， 它 意味 着 如 
果 epoll 再 次 检测 到 可 读 事件 或 者 读 事 件 的 定时 器 超时 ，HTTP 框 染 将 调 
用 ngx_http_read_client_request_body_handler 方 法 处 理 ， 该 方法 所 做 的 工 
作 参 见 图 11-15。 


7) 调用 ngx_http_do_read_client_request_body 方 法 接收 包 体 。 该 方 
法 的 意义 在 于 把 客户 端 与 Nginx 之 间 TCP 连 接 上 套 接 字 绥 冲 区 中 的 当前 
字符 流 全 部 读 出 来 ， 并 判断 是 否 需 要 写 入 文件 ， 以 及 是 否 接 收 到 全 部 的 


包 体 ， 同 时 在 接收 到 完整 的 包 体 后 激活 post_handler 回 调 方法 ， 如 图 11- 


14 所 示 。 


[检查 request 9 接收 包 体 缓冲 区 ] 





[缓冲 区 写 满 ] 


[缓冲 区 上 还 有 空闲 空间 ] 









1 ) 将 缓冲 区 中 数据 
写 入 临时 文件 





2) 重 置 ngxbuf t+ 缓冲 区 里 的 
os 、last 参 : 
[ 仍 有 可 接收 的 字符 流 ] 
3) 将 TCP 连 接 套 接 字 上 的 
字符 流 读 取 到 缓冲 区 
[检查 recv 方 法 的 返回 值 ] 






[出 现 错误 或 者 客户 端 关闭 了 连接 ] 


[接收 到 字符 流 ] 


4) 设置 error 标 志 位 为 1， 
5 ) 根据 接收 内 容 修改 


缓冲 区 的 last 参 数 


> 


[已 接收 到 全 部 的 包 体 ,检查 定时 器 中 是 否 还 在 监控 读 事件 ] 





[ 套 接 字 缓 冲 区 中 没有 可 读数 据 ] 





6) 将 读 事 件 添加 





到 定时 器 
[ 读 事 件 还 在 定时 器 中 ] 「 读 事件 不 在 定时 器 中 | 







8 ) 将 读 事 件 从 定时 器 
中 删除 


7) 将 读 事件 添加 到 epoll 









并 返回 NGX_AGAIN 


9 ) 将 缓冲 区 剩余 内 容 
写 入 临时 文件 


10) 重新 设置 后 续 接 收 连接 上 TCP 流 的 


read_event_handler 方 法 





11) 调用 HTTP 模 块 要 求 回调 的 @ 


ost_handler 方 法 


图 11-14 hpgx_http_do_tread_client_ tequest body 方法 的 流程 图 


图 11-14 中 列 出 的 ngx_http_do_read_client_request_body 方 法 流程 稍 


显 复杂 ， 下 面 详 细 解 释 一 下 这 11 个 步骤 。 


1) 首先 检查 请 求 的 request_body 成 员 中 的 buf 缓 冲 区 ， 如 果 绥 冲 区 
还 有 空闲 的 空间 ， 则 跳 到 第 3 步 读 取 内 核 中 套 接 字 缓冲 区 里 的 TCP 字 符 
流 :， 如 果 绥 冲 区 已 经 写 满 ， 则 调用 ngx_http_write_request_body 方 法 把 组 
冲 区 中 的 字符 流 写 入 文件 。 


2) 通过 第 1 步 把 request_body 绥 冲 区 中 的 内 容 写 入 文件 后 ， 绥 冲 区 
就 可 以 重复 使 用 了 ， 只 需要 把 缓冲 区 ngx_buf _t 结 构 体 的 last 指 针 指 癌 
start 指 针 ， 绥 冲 区 即 可 复 用 。 


3) 调用 封装 了 recv 的 方法 从 套 接 字 绥 冲 区 中 读 取 包 体 到 缓冲 区 
中 。 如 宁 recv 方 法 返回 错误 ， 或 者 客户 端 主动 关闭 了 连接 ， 则 跳 到 第 4 
步 执 行 ， 如 果 读 取 到 内 容 ， 则 跳 到 第 5 步 执行 。 


4) 设置 ngx_http_redquest t 结 构 体 的 error 标 志 位 为 1， 同 时 返回 


NGX_HTTP BAD_REQUEST 错 误 码 。 


5) 根据 接收 到 的 TCP 流 长 上 度 ， 修 改 缓冲 区 参数 。 例 如 ， 把 缓冲 区 
ngx_buf_t 结 构 体 的 last 指 针 加 上 接收 到 的 长 度 ， 同 时 更 新 request_body 结 
构 体 中 表示 待 接收 的 剩余 包 体 长 度 的 rest 成 员 、 更 新 ngx_http_request_t 结 
构 体 中 表示 已 接收 请 求 长 度 的 request_length 成 员 。 


根据 rest 成 员 检 查 是 否 接收 到 完整 的 包 体 ， 如 果 接 收 到 了 完整 的 包 
体 ， 则 路 到 第 8 步 继续 执 行 ， 人 否则 得 看 套 接 字 绥 名 区 上 和 是否 仍然 有 可 读 
的 字符 流 ， 如 条 有 则 跳 到 第 1 步 继续 接收 包 体 ， 如 果 没 有 则 跳 到 第 6 步 。 








6) 如 果 当 前 已 经 没有 可 读 的 字符 流 ， 同 时 还 没有 接收 到 完整 的 包 
体 ， 则 说 明 需 要 把 读 事件 添加 到 事件 模块 ， 等 待 可 读 事 件 发 生 时 ， 事 件 
框架 可 以 再 次 调度 到 这 个 方法 接收 包 体 。 这 一 步 是 调用 ngx_add_timer 方 
法 将 读 事 件 添 加 到 定时 器 中 ， 超 时 时 间 以 nginx.conf 文 件 中 的 
client_body_timeout 配 置 项 参数 为 准 。 





7) 调用 ngx_handle_read_event 方 法 将 读 事 件 添加 到 epoll 等 事件 收集 
器 中 ， 同 时 ngx_http_do_read_client_request_body 方 法 结束 ， 返 回 
NGX_AGAIN。 


8) 到 这 一 步 ， 表 明 已 经 接收 到 完整 的 包 体 ， 需 要 做 一 些 收尾 工作 
了 。 首 先 不 需要 检查 是 否 接 收 HTTP 包 体 超 时 了 ， 要 把 读 事件 从 定时 器 
中 取出 ， 防 止 不 必要 的 定时 器 触发 。 这 一 步 会 检查 读 事 件 的 timer_set 标 
志 位 ， 如 果 为 1， 则 调用 ngx_del_timer 方 法 把 读 事 件 从 定时 器 中 移 除 。 








9) 如 采 绥 冲 区 中 还 有 未 写 入 文件 的 内 容 ， 调 用 
ngx_http_write_request_body 方 法 把 最 后 的 包 体 内 容 也 写 入 文件 。 


10) 在 图 11-13 的 第 5 步 中 曾经 把 请 求 的 read_event_handler 成 员 设 置 


为 ngx_http_read_client_request_body_handler 方 法 ， 现 在 既然 已 经 接收 到 


完整 的 包 体 了 ， 就 会 把 read_event_handler 设 为 ngx_http_block reading 方 
法 ， 表 示 连 接 上 再 有 读 事件 将 不 做 任何 处 理 。 


11) 执行 HTTP 模块 提供 的 post_handler 回 调 方法 后 ， 
ngx_http_do_read_client_request_body 方 法 结束 ， 返 回 NGX_OK。 


图 11-13 中 的 第 6 步 把 请 求 的 read_event_handler 成 员 设 置 为 
ngX_http_read_client_request_body_handler 方 法 ， 从 11.6 节 的 图 11-7 可 以 
看 出 ， 这 个 请 求 连接 上 的 读 事件 触发 时 的 回调 方法 
ngx_http_request_handler 会 调用 read_event_handler 方 法 ， 下 面 根据 图 11- 
15 来 看 看 这 时 ngx_http_read_client_request_body_handler 方 法 做 了 些 什 


2 


[检查 读 取 HTTP 包 体 是 否 超 时 ] 






[ 读 事件 未 超时 ] 


[ 读 事件 已 经 超时 ] 






1 ) 调用 ngx_http_finalize_request 
结束 请 求 并 发 送 408 响 应 







2 ) 调用 ngx_http_do _read_client _request _body 方 法 接收 包 体 








[返回 值 大 于 或 等 于 300] 











3) 以 上 一 步 返 回 值 为 参数 调用 
ngx_http _finalize_request 结束 请 求 





图 11-15 ngx_http_read_client_request_body_handler 方 法 的 流程 图 
简单 解释 一 下 图 11-15 中 的 3 个 步 又。 


1) 首先 检查 连接 上 读 事件 的 timeout 标 志 位 ， 如 果 为 1， 则 表示 接收 
HTTP 包 体 超 时 ， 这 时 把 连接 ngx_connection_t 结 构 体 上 的 timeout 标 志 位 
也 置 为 1， 同 时 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 并 发 送 408 
超时 错误 码 。 如 果 没 有 超时 ， 则 跳 到 第 2 步 执行 。 





2) 调用 图 11-14 中 介绍 的 ngx_http_do_read_client_request_body 方 法 
接收 包 体 ， 检 测 这 个 方法 的 返回 值 ， 如 果 它 大 于 300， 那 么 一 定 表示 和 希 
望 返 回 错误 码 。 例 如 ， 图 11-14 的 第 4 步 就 返回 了 400 错 误 码 ， 这 时 跳 到 
第 3 步 执行 ， 否 则 ngx_http_read_client_request_body_handler 方 法 结束 ， 
直接 返回 NGX_OK。 


3) 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 第 2 个 参数 传递 的 


是 ngx_http_do_read_client_request_body 方 法 的 返回 值 ， 详 见 11.10.6 节 。 


以 上 3 个 方法 完整 地 描述 了 HTTP 框 架 接收 包 体 的 流程 ， 以 及 最 后 如 
何 执行 HITP 模 块 实现 的 post_handler 方 法 。 读 者 可 以 参照 它 再 看 看 第 3 章 
中 开发 HTTP 模 块 时 是 如 何 接收 包 体 的 ， 相 信 经 过 本 章 的 分 析 ， 读 者 会 
对 这 一 机 制 有 新 的 认识 。 


11.8.2 ”放弃 接收 包 体 








对 于 HTTP 模 块 而 言 ， 放 弃 接 收 包 体 就 是 简单 地 不 处 理 包 体 了 ， 可 
是 对 于 HTTP 框 架 而 言 ， 并 不 是 不 接收 包 体 就 可 以 的 。 因 为 对 于 客户 端 
而 言 ， 通 常会 调用 一 些 阻塞 的 发 送 方法 来 发 送 包 体 ， 如 果 HITTP 框 架 一 
直 不 接收 包 体 ， 会 导致 实现 上 不 够 健壮 的 客户 端 认 为 服务 器 超时 无 响 
应 ， 因 而 简单 地 关闭 连接 ， 可 这 时 Nginx 模 块 可 能 还 在 处 理 这 个 连接 。 
因此 ，HTTP 模 块 中 的 放弃 接收 包 体 ， 对 HTTP 框 架 而 言 就 是 接收 包 体 ， 











但 是 接收 后 不 做 保存 ， 和 直接 丢 弃 。 


HTTP 框 架 提 供 了 一 个 方法 一 ngx_http_discard_request_body 用 于 丢 
弃 包 体 ， 使 用 上 也 非常 简单 ， 直 接 调 用 这 个 方法 就 可 以 了 ， 不 像 11.8.1 
节 中 接收 包 体 一 样 还 需要 一 个 回调 方法 。 下 面 先 来 看 看 
ngx_http_discard_request_body 方 法 的 定义 。 


ngx_int_t ngx_http_discard request_ body(ngx_http_request _t *r) 











可 以 看 到 ， 它 是 没有 post_handler 回 调 方法 的 ， 那 么 接收 完全 部 的 包 
体 后 怎么 办 呢 ? 很 简单 ， 在 图 11-18 的 第 3 步 就 是 接收 到 全 部 包 体 后 的 动 
作 ， 其 代码 如 下 所 示 。 


ngx_http_finalize_request(r, NGX_DONE); 





这 里 实际 上 相当 于 把 原始 请 求 的 引用 计数 减 1 了 ， 当 然 ， 如 果 引 用 
计数 为 0( 如 HTTP 模 块 已 经 调用 过 结束 请 求 的 方法 ) ， 还 是 会 真正 结束 
请 求 的 。 





放弃 接收 包 体 和 接收 包 体 的 实现 方式 是 极其 相似 的 ， 它 也 使 用 了 3 
个 方法 实现 ，HTTP 模 块 调用 的 ngx_http_discard_request_body 方 法 用 于 
第 一 次 启动 丢弃 包 体 动作 ， 而 ngx_http_discarded_request_body_handler 
是 作为 请 求 的 read_event_handler 方 法 的 ， 在 有 新 的 可 读 事件 时 会 调用 它 
处 理 包 体 。ngx_http_read_discarded_request_body 方 法 则 是 根据 上 述 两 个 











方法 通用 部 分 提取 出 的 公共 方法 ， 用 来 读 取 包 体 且 不 做 任何 处 理 。 


下 面 看 看 ngx_http_discard_request_body 方 法 做 了 些 什 么 ， 如 图 11-16 
所 示 。 





下 面 解释 一 下 图 11-16 中 所 列 的 7 个 步 又 。 











1) 首先 检查 当前 请 求 是 一 个 子 请 求 还 是 原始 请 求 。 为 什么 要 检查 
这 个 呢 ? 因为 对 于 子 请 求 而 言 ， 它 不 是 来 目 客户 端的 请 求 ， 所 以 不 存在 
处 理 HTTP 请 求 包 体 的 概念 。 如 果 当 前 请 求 是 原始 请 求 ， 则 跳 到 第 2 步 中 

续 执行 ， 如 果 它 是 子 请 求 ， 则 直接 返回 NGX_OK 表 示 丢 弃 包 体 成 功 。 











2) 检查 请 求 连 接 上 的 读 事件 是 否 在 定时 器 中 ， 这 是 因为 丢弃 包 体 
不 用 考虑 超时 问题 (linger_timer 例 外 ， 本 章 不 考虑 此 情况 ) 。 如 果 读 事 
件 的 timer_set 标 志 位 为 1， 则 从 定时 器 中 移 除 此 事件 。 还 要 检查 content- 
length 头 部 ， 如 果 它 的 值 小 于 或 等 于 0， 同 样 意味 着 可 以 直接 返回 
NGX_OK， 表 示 成 功 丢弃 了 全 部 包 体 。 或 者 检查 ngx_http_request_t 结 构 
体 的 request_body 成 员 ， 如 果 它 已 经 被 赋值 过 且 不 再 为 NULL 衬 指针， 则 
说 明 已 经 接收 过 包 体 了 ， 这 时 也 需要 返回 NGX_OK 表 示 成 功 。 








3) 吏 像 11.8.1 市 中 介绍 的 那样 ， 在 接收 HTTP 头 部 时 ， 还 是 要 检查 

否 读 巧 已 经 接收 到 完整 的 包 体 〈 如 果 包 体 很 小 ， 那 么 这 是 非常 可 能 发 
生 的 事 ) ， 如 果 已 经 接收 到 完整 的 包 体 ， 则 中 到 第 1 步 直 接 返 回 
NGX_OK， 表 示 丢 弃 包 体 成 功 ， 否 则 ， 说 明 需 要 多 次 的 调度 才能 完成 丢 


弃 包 体 这 一 动作 ， 此 时 把 请 求 的 read_event_handler 成 员 设 置 为 
ngx_http_discarded_request_body_handler 方 法 。 


[检查 当前 请 求 是 否 可 以 放弃 包 体 ] 





[检查 连接 上 的 读 事件 是 否 在 定时 器 中 ] 
[当前 请 求 不 是 原始 请 求 ， 或 者 包 体 已 经 丢弃 ] 





[ 读 事 件 在 定时 器 中 ] 


[ 读 事件 不 在 定时 器 中 ] 2 ) 将 读 事件 从 





















定时 需 中 移 除 
[检查 content-length 头 部 ] 


[content_length 小 于 或 等 于 0, 或 者 已 经 接收 过 包 体 ] 
[检查 header_in 缓 冲 区 ] 
[在 headerin 缓 冲 区 里 接收 到 完整 的 包 体 ] 


[header_ in 缓冲 区 中 未 接收 到 完整 包 体 ] 

















3) 设置 后 续 接收 连接 上 
TCP 流 的 read_event_handler 方 法 








4) 将 读 事 件 
添加 到 epoll 中 


5 ) 调用 ngx_http_read_discarded_request_body 
接收 包 体 并 丢弃 
[检查 方法 的 返回 值 ] 






[返回 NGX_OK] 
[返回 非 NGX_OK] 


6 ) count 引 用 计数 加 1 
并 返回 NGX_OK 


7) 设置 延迟 关闭 标志 位 为 0 
并 返回 NGX _OK 


图 11-16 ”ngx_http_discard_request_body 方 法 的 流程 图 


4) 调用 ngx_handle_read_event 方 法 把 读 事件 添加 到 epoll 中 。 


5) 调用 ngx_http_read_discarded_request_body 方 法 接收 包 体 ， 检 测 
它 的 返回 值 。 如 果 返 回 NGX_OK， 则 跳 到 第 7 步 ， 否 则 跳 到 第 6 步 。 





返回 非 NGX_OK 表 示 Nginx 的 事件 框架 触发 事件 需要 多 次 调度 才 
能 完成 丢弃 包 体 这 一 动作 ， 于 是 先 把 引用 计数 加 1， 防 止 这 边 还 在 丢弃 
包 体 ， 而 其 他 事件 却 已 让 请 求 意外 销毁 ， 引 发 严重 错误 。 同 时 把 
ngx_http_request_t 结 构 体 的 discard_body 标 志 位 置 为 1， 表 示 正 在 丢弃 包 
体 ， 并 返回 NGX_OK， 当 然 ， 这 时 的 NGX_OK 绝 不 表示 已 经 成 功 地 接 
收 完 包 体 ， 只 是 说 明 ngx_http_discard_request_body 执 行 完 毕 而 已 。 











) 返回 NGX_OK 表 示 已 经 接收 到 完整 的 包 体 了 ， 这 时 将 请 求 的 
lingering_close 延 时 关闭 标志 位 设 为 0， 表 示 不 需要 为 了 包 体 的 接收 而 延 
时 关闭 了 ， 同 时 返回 NGX_OK 表 示 丢 弃 包 体 成 功 。 





从 以 上 步骤 可 以 看 出 ， 当 ngx_http_discard_request_body 方 法 返回 
NGX_OK 时 ， 是 可 能 表达 很 多 意思 的 。HTTP 框 架 的 目的 是 希望 各 个 
HTTP 模 块 不 要 去 关心 丢弃 包 体 的 执行 情况 ， 这 些 工作 完全 由 HTTP 框 架 
完成 ; 








下 面 再 看 看 在 第 5 步调 用 的 ngx_http_read_discarded request_body 方 
法 的 执行 流程 ， 如 图 11-17 所 示 。 


Ee 


今 查 还 需要 接收 的 包 体 长 度 headers_in. content_Jength_n] 


[丢弃 的 包 体 长 度 已 经 达到 content-length 指 定 长 度 ] 


[还 有 包 体 需要 处 理 ] 1) 设置 后 续 接收 连接 上 TCP 流 的 


read_event handle 访 法 


[ 套 接 字 缓 冲 区 上 没有 可 读 内 容 ] 


[ 套 接 字 上 有 可 读 TCP 流 ] 


3) 由 TCP 连 接 的 套 接 字 缓 冲 区 
中 读 取 请 求 的 包 体 
[检查 recv 接 收 方法 的 返回 值 ] 
[大 , 接 字 缓冲 区 已 空 ， 
需要 继续 读 取 包 体 ] 2) 返回 
NGX _ AGAIN 





[客户 端 关闭 了 连接 ] 


5) 更 新 已 乡 至 丢弃 
的 包 体 长 度 





图 11-17 ngx_http_read_discarded_request_body 方 法 的 流程 图 


可 以 看 到 ， 虽 然 ngx_http_read_discarded_request_body 方 法 与 
ngx_http_do_read_client_request_body 方 法 很 类 似 ， 但 前 者 比 后 者 简单 多 
了 ， 毕 竟 不 需要 保存 接收 到 的 包 体 。 下 面 简单 分 析 一 下 图 11-17 中 的 5 个 
步 又 。 








~ 


1) 丢弃 包 体 时 请 求 的 request_body 成 员 实 际 上 是 NULL 空 指针 ， 那 
么 用 什么 变量 来 表示 已经 丢弃 的 包 体 有 多 大 呢 ? 实 际 上 这 时 使 用 了 请 求 











ngx_http_request_t 结 构 体 headers_in 成 员 里 的 content_length_n， 最 初 它 等 
于 content-length 头 部 ， 而 每 于 弃 一 部 分 包 体 ， 就 会 在 content_length_n 变 
量 中 减 去 相应 的 大 小 。 因 此 ，content_length_n 表 示 还 需要 丢弃 的 包 体 长 
度 ， 这 里 首先 检查 请 求 的 content_length_n 成 员 ， 如 果 它 已 经 等 于 0， 则 
表示 已 经 接收 到 完整 的 包 体 ， 这 时 要 把 read_event_handler 重 置 为 
ngx_http_block_reading 方 法 ， 表 示 如 果 再 有 可 读 事件 被 触发 时 ， 不 做 任 
何 处 理 。 同 时 返回 NGX_OK， 告 诉 上 层 的 方法 已 经 丢弃 了 所 有 包 体 。 








2) 如 果 连 接 套 接 字 的 缓冲 区 上 没有 可 读 内 容 ， 则 直接 返回 
NGX_AGAIN， 告 诉 上 层 方法 需要 等 待 读 事件 的 触及 ， 等 待 Nginx 框 架 
的 再 次 调度 。 








3) 调用 recv 方 法 读 取 包 体 。 根 据 返 回 值 确 定 ， 如 末 套 接 字 缓冲 区 
中 没有 读 取 到 内 容 ， 而 需要 继续 读 取 则 跳 到 第 2 步 ， 如 果 客 户 闻 主动 关 
闭 了 连接 ， 则 跳 到 第 4 步 ， 如 果 读 取 到 了 内 容 ， 则 跳 到 第 5 步 。 





4) 既然 客户 端 主动 关闭 了 连接 ， 直 接 返 回 NGX_OK 告 诉 上 层 方法 
结束 丢弃 包 体 动作 即 可 。 








5) 接收 到 包 体 后 ， 要 更 新 请 求 的 content_length_n 成 员 (参见 第 1 步 
中 的 描述 ) ， 同 时 再 跳 回 到 第 1 步 准备 再 次 接收 包 体 。 








最 后 再 看 看 请 求 的 ngx_handle_read_event 指 定 的 
ngx_http_discarded_request_body_handler 方 法 ， 在 新 的 可 读 事 件 被 触发 


时 ，HTTP 框 架 将 会 调用 它 来 处 理事 件 ， 图 11-18 给 出 了 该 方法 的 流程 。 


[检查 连接 上 的 读 事 件 是 否 超时 ] 
[已 经 接收 请 求 超时 ] 





> 


超时 ] 1 ) 调 用 ngx_http_finalize _request 
方法 结束 请 求 


[接收 请 求 









2 调用 ngx_http_read_discarded_request_body 
方法 接收 包 体 
[检查 方法 的 返回 值 ] 

[返回 值 是 NGX _OKI] 
















3) 调用 ngx_http_finalize_request 
方法 结束 请 求 ， 参 数 为 NCX_DONE 


4) 将 读 事 件 添加 到 epol 中 








图 11-18 ngx_http_discarded_request_body_handlet 方 法 的 流程 图 


实际 上 ，ngx_http_discarded_request_body_handler 方 法 还 涉及 
lingering_time 的 处 理 ， 为 了 减少 非 主干 内 容 的 篇 幅 ， 本 章 将 不 涉及 此 内 
容 ， 因 此 图 11-18 中 也 没有 给 出 。 下 面 分 析 一 下 图 11-18 中 的 4 个 步骤 : 


1) 首先 检查 TCP 连 接 上 的 读 事件 的 timedout 标 志 位 ， 为 1 时 表示 已 
经 超时 ， 这 时 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 传 递 的 参数 
是 NGX ERROR， 流 程 结束 。 


2) 调用 ngx_http_read_discarded_request_body 方 法 接收 包 体 ， 检 测 


其 返回 值 。 如 果 返 回 NGX_OK， 则 跳 到 第 3 步 执行 ， 人 否则 跳 到 第 4 步 。 





3) 此 时 表示 已 经 成 功 地 丢弃 完 所 有 的 包 体 ， 这 一 步骤 将 请 求 的 正 
在 丢弃 包 体 discard_body 标 志 位 置 为 0， 将 延迟 关闭 标志 位 lingering_close 
也 置 为 0， 再 调用 ngx_http_finalize_request 方 法 结束 请 求 注 意 ， 它 的 第 2 
个 参数 是 NGX_DONE，11.10.6 节 将 会 介绍 NGX_DONE 参 数 引 发 的 动 
作 。 然 后 流程 结 


4) 仍然 需要 调用 ngx_handle_read_event 方 法 把 读 事 件 添加 到 epoll 
中 ， 期 竺 新 的 可 读 事件 到 来 。 





以 上 介绍 了 丢弃 包 体 的 全 部 流程 ， 可 以 看 到 ， 这 个 简单 的 动作 其 实 
也 需要 很 多 步骤 才能 完成 ， 但 它 非 各 高 效 ， 没 有 任何 阻 寨 进程 ， 也 没有 
让 进程 休眠 的 操作 。 同 时 ， 对 于 HTTP 模 块 而 言 ， 它 使 用 起 来 也 比较 简 
单 ， 值 得 读者 学 习 。 


11.9 ”发 送 HTTP 响 应 





本 节 开 始 讨论 第 3 章 中 己 出 现 过 的 发 送 HTTP 响 应 的 两 个 方法 : 
ngx_http_send_header 方 法 和 ngx_http_output_filter 方 法 。 这 两 个 方法 将 负 
责 把 HITP 响 应 中 的 应 答 行 、 头 部 、 包 体 发 送 给 客户 端 。Nginx 是 一 个 全 
异步 的 事件 驱动 架构 ， 那 么 仅仅 调用 ngx_http_send_header 方 法 和 
ngx_http_output_filter 方 法 ， 惑 可 以 把 响应 全 部 发 送 给 客户 端 吗 ? 当然 不 
是 ， 当 响应 过 大 无 法 一 次 发 送 完 时 〈TCP 的 滑动 窗口 也 是 有 限 的 ， 一 次 
非 阻塞 的 发 送 多 半 是 无 法 发 送 完整 的 HITP 响 应 的 ) ， 就 需要 向 epoll 以 
及 定时 器 中 添加 写 事件 了 ， 当 连接 再 次 可 写 时 ， 就 调用 ngx_http_writer 
方法 继续 发 送 响应 ， 直 到 全 部 的 响应 都 发 送 到 客户 端 为 止 。 














以 上 大 致 说 了 一 下 HTTP 框 架 为 发 送 响应 所 要 做 的 工作 ， 然 而 ， 对 
于 各 个 HTTP 模 块 而 言 ， 绝 大 多 数 情况 下 发 送 HTTP 啊 应 时 就 是 这 个 请 求 
结束 的 时 候 ， 难 道 说 还 要 像 接收 包 体 那 样 ， 传 递 一 个 post_handler 回 调 方 
法 ， 等 所 有 的 响应 都 发 送 完 时 再 回调 HTTP 模 块 的 post_handler 方 法 来 关 
闭 请 求 吗 ? 这 个 设计 显然 是 不 好 的 ， 根 据 HTTP 的 特点 ， 只 要 开始 发 送 
响应 基本 上 可 以 确定 请 求 就 要 结束 了 。 因 此 ，HTTP 采 用 的 设计 是 ， 使 
用 ngx_http_output_filter 方 法 发 送 啊 应 时 ， 必 须 与 结束 请 求 的 
ngx_http_finalize_request 方 法 配合 使 用 (ngx_http_finalize_request 方 法 会 
把 请 求 的 write_event_handler 设 置 为 ngx_http_writer 方 法 ， 并 将 写 事件 添 





加 到 epol 和 定时 器 中 ) ， 这 样 就 使 得 真正 负责 在 后 台 异 步 地 发 送 啊 应 的 
ngx_http_writer 方 法 对 HTTP 模 块 而 言 也 是 透明 的 。 





11.9.1 贡 中 将 介绍 发 送 HTTP 啊 应 行 、 头 部 的 ngx_http_send_header 方 
法 ，11.9.2 节 将 介绍 发 送 啊 应 包 体 的 ngx_http_output_filter 方 法 ， 同 时 在 
这 两 节 中 还 会 穿插 介绍 如 何 配 合 ngx_http_finalize_request 方 法 使 用 ， 实 
现 异 步 的 发 送 机 制 。 最 后 在 11.9.3 节 会 介绍 在 后 台 发 送 响应 的 
ngx_http_writer 方 法 。 





11.9.1 ngx_http_send header 


ngx_http_send_header 方 法 负责 构造 HITP 响 应 行 、 头 部 ， 同 时 会 把 

它们 发 送 给 客户 端 。 发 送 啊 应 头 部 使 用 了 第 6 章 所 述 的 流水 线 式 的 过 滤 
模块 思想 ， 即 通过 提供 统一 的 接口 ， 让 各 个 感 兴趣 的 HTTP 模 块 加 入 到 
ngx_http_send_header 方 法 中 ， 然 后 通过 每 个 过 滤 模 块 C 源 文件 中 独 有 的 
ngx_http_next_header_filter 指 针 将 各 个 过 滤 尖 部 的 方法 连接 起 来 ， 
样 ， 在 调用 ngx_http_send_header 方 法 时 ， 实 际 就 是 依次 调用 了 所 有 头 部 
过 滤 模 块 的 方法 ， 其 中 ， 链 表 里 的 最 后 一 个 头 部 过 滤 方 法 将 负责 发 送 头 
部 。 因 此 ， 这 些 过 滤 模 块 组 成 的 链表 顺序 是 非常 重要 的 ， 我 们 在 第 6 章 
的 6.2.1 节 和 6.2.2 节 已 经 介绍 过 这 部 分 内 容 ， 这 里 不 再 鳌 述 

















调用 ngx_http_send_header 方 法 时 ， 最 后 一 个 头 部 过 滤 模 块 叫 做 


ngx_http_header_filter_ module 模 块 ， 之 前 的 头 部 过 滤 模 块 会 根据 特性 去 
修改 表示 请 求 的 ngx_http_request_t 结 构 体 中 headers_out 成 员 里 的 内 容 ， 
而 最 后 一 个 头 部 过 滤 模 块 ngx_http_header _filter_ module 提 供 的 
ngx_http_header filter 方 法 则 会 根据 HTTP 规 则 把 headers_out 中 的 成 员 变 
量 序列 化 为 字符 流 ， 并 发 送出 去 ， 而 本 节 的 重点 就 在 于 说 明 
ngx_http_header_filter 方 法 所 做 的 工作 。 








在 了 解 ngx_http_header filter 方 法 之 前 ， 我 们 还 是 得 先 回 顾 一 下 事件 
驱动 机 制 ， 因 为 它 要 求 任 何 操作 都 不 可 以 阻塞 进 程 ， 
ngx_http_header _filter 方 法 当然 也 不 能 例外 。 那 么 ， 如 果 要 发 送 的 啊 应 头 
部 大 于 套 接 字 可 写 的 缓存 ， 无 法 一 次 把 响应 头 部 发 送出 去 怎么 办 ? 这 就 
需要 使 用 ngx_http_request_t 结 构 体 中 ngx_chain_t 类 型 的 成 员 out 了 ， 它 将 
会 保存 没有 发 送 完 的 〈 剩 余 的 ) 响应 头 部 。 那 么 ， 什 么 时 候 发 送 请 求 
out 成 员 中 保存 的 剩余 响应 头 部 呢 ? 这 就 要 结合 用 于 结束 请 求 的 
ngx_http_finalize_request 方 法 来 说 了 。 

















当 ngx_http_header _ filter 方法 无 法 一 次 性 发 送 HITP 头 部 时 ， 将 会 有 
以 下 两 个 现象 同时 发 生 。 





请求 的 out 成 员 中 将 会 保存 剩余 的 响应 头 部 。 


ngx_http_header_filter 方 法 返回 NGX_AGAIN。 





如 果 这 个 啊 应 没有 包 体 ， 那 么 这 时 通常 已 经 可 以 调用 


ngx_http_finalize_request 方 法 来 结束 请 求 了 ， 参 见 11.10.6 市 中 
ngx_http_finalize_request 方 法 的 原型 ， 它 的 第 2 个 参数 很 关键 ,我们 需要 
把 NGX_AGAIN 传 进去 ， 这 样 ngx_http_finalize_request 方 法 就 理解 了 实 
际 上 还 需要 HTTP 框 架 继续 发 送 请 求 out 成 员 中 保存 的 剩余 啊 应 字符 流 。 
ngx_http_finalize_request 方 法 会 设置 请 求 的 write_event_handler 成 员 为 
ngx_http_writer 方 法 ， 这 样 ， 当 连接 上 有 可 写 事件 时 ， 束 会 调用 11.9.3 节 
描述 的 ngx_http_writer 方 法 继续 发 送 剩余 的 HTTP 啊 应 。 下 面 先 来 看 看 
ngx_http_header filter 方 法 的 流程 图 ， 如 图 11-19 所 示 。 








[检查 请 求 的 header_sent 标志 位 ] 


We 
[header_sent 标 志 位 为 0] [isaidierssent 标志 位 为 1 ] 


2 ) 将 header_sent 





标志 位 置 为 1 
[检查 当前 请 求 是 于 请 求 还 是 原始 请 求 ] 


[ 当前 请 求 不 是 原始 请 求 ] 





[当前 请 求 是 原始 请 求 , 青 检查 请 求 的 HTTP 版 本 ] 
[HTTP 版 本 小 于 1.0] 


[HTTP 版 本 为 .0 或 者 1 1] 


3) 计算 啊 应 行 、 1) 返 回 
头 部 序列 化 后 字符 流 长 度 NGX_OK 


4) 在 内 存 池 上 分 配 用 于 
存放 响应 字符 流 的 缓存 


5 ) 将 响应 行 、 
头 部 按 规则 序列 化 到 缓存 中 


6) 调 用 ngx_http_write_filter 
方法 发 送 构造 好 的 缓存 





E> 


图 11-19 ”ngx_http_header_filter 方 法 的 流程 图 


下 面 描 述 一 下 图 11-19 中 的 6 个 步骤 。 


1) 首先 检查 请 求 ngx_http_request_t 结 构 体 的 header_sent 标 志 位 ， 如 
果 header_sent 为 1， 则 表示 这 个 请 求 的 响应 头 部 已 经 发 送 过 了 ， 不 需要 
再 向 下 执行 ， 直 接 返 回 NGX_OK 即 可 。 











2) 正式 进入 发 送 啊 应 头 部 阶段 ， 为 防止 反复 地 发 送 啊 应 头 部 ， 将 
header_sent 标 志 位 置 为 1。 同 时 需要 检查 当前 请 求 是 否 是 客户 端 发 来 的 
原始 请 求 ， 如 果 当 前 请 求 只 是 一 个 子 请 求 ， 它 是 不 存在 发 送 HITP 响 应 
头 部 这 个 概念 的 ， 因 此 ， 如 果 当 前 请 求 不 是 main 成 员 指 向 的 原始 请 求 
时 ， 跳 到 第 1 步 直接 返回 NGX_OK。 如 果 HTTP 版 本 小 于 1.0， 同 样 不 需 
要 发 送 响 应 头 部 ， 仍 然 跳 到 第 1 步 返 回 NGX_OK。 


























3) 根据 请 求 headers_out 结 构 体 中 的 错误 码 、HTTP 头 部 字符 串 ， 计 
算出 如 果 把 啊 应 头 部 序列 化 为 一 个 字符 串 共 需要 多 少 字 节 。 














4) 在 请 求 的 内 存 池 中 分 配 第 3 步 计 算出 的 缓冲 区 。 





5) 将 啊 应 行 、 涉 部 按照 HTTP 的 规范 序列 化 地 复制 到 缓冲 区 中 。 


6) 将 第 4 步 中 分 配 的 缓冲 区 作为 参数 调用 ngx_http_write_filter 方 
法 ， 将 响应 头 部 发 送出 去 。 





注意 ， 第 6 步 是 通过 调用 ngx_http_write_filter 方 法 来 发 送 响应 头 部 
的 。 事 实 上 ， 这 个 方法 是 包 体 过 滤 模 块 链表 中 的 最 后 一 个 模块 








ngx_http_write_filter_module 的 处 理 方 法 ， 当 HTTP 模 块 调用 
ngx_http_output_filter 方 法 发 送 包 体 时 ， 最 终 也 是 通过 该 方法 发 送 啊 应 的 
《在 11.9.2 节 中 将 详细 地 介绍 这 一 方法 ) 。 当 一 次 无 法 发 送 全 部 的 缓冲 
区 内 容 时 ，ngx_http_write_filter 方 法 是 会 返回 NGX_AGAIN 的 (同时 将 
未 发 送 完成 的 缓冲 区 放 到 请 求 的 out 成 员 中 ) ， 也 就 是 说 ， 发 送 啊 应 头 
部 的 ngx_http_header_filter 方 法 会 返回 NGX_AGAIN。 如 果 不 需 要 再 发 送 
包 体 ， 那 么 这 时 就 需要 调用 ngx_http_finalize_request 方 法 来 结束 请 求 ， 
其 中 第 2 个 参数 务必 要 传递 NGX_AGAIN， 这 样 HTTP 框 架 才 会 继续 将 可 
写 事件 注册 到 epoll， 并 持续 地 把 请 求 的 out 成 员 中 缓冲 区 里 的 HTTP 响 应 
发 送 完 毕 才 会 结束 请 求 。 





11.9.2 ngx_http_output filter 


ngx_http_output_filter 方 法 用 于 发 送 啊 应 包 体 ， 它 的 第 2 个 参数 束 是 
用 于 存放 响应 包 体 的 缓冲 区 ， 如 下 所 示 。 








ngx_int_t ngx_http_write_filter(ngx_http_redquest_t *r, ngx_chain_t *in) 











其 中 第 2 个 参数 ip 在 第 6 章 中 已 有 过 详细 的 介绍 ， 这 里 不 再 歼 述 。 用 
于 过 滤 包 体 的 HTTP 模块 将 以 ngx_http_next_body _filter 作 为 链表 指针 连 
接 成 一 个 流水 线 ，ngx_http_output_filter 方 法 在 发 送 包 体 时 会 依次 调用 各 
个 过 滤 包 体 方 法 ， 其 中 最 后 一 个 过 滤 包 体 方法 就 是 11.9.1 节 中 介绍 过 的 





ngx_http_write_filter 方 法 ， 它 属于 ngx_http_write_filter_module 模 块 。 





本 节 与 ngx_http_send_header 方 法 的 介绍 一 样 ， 不 会 讨论 每 个 过 滤 模 
块 的 功能 ， 我 们 只 看 最 后 一 个 包 体 过 滤 模 块 是 怎样 发 送 响应 包 体 的 。 在 
图 11-20 中 ，ngx_http_write_filter 方 法 展示 了 HTTP 框 架 是 如 何 开 始 发 送 
HTTP 响 应 包 体 的 。 








图 11-20 中 描述 的 ngx_http_write_filter 方 法 主要 有 13 个 步 台 ,下面 详 
细 介 绍 这 些 步骤 到 底 是 如 何 工 作 的 。 


1) 首先 检查 请 求 的 连接 Fngx_connection_t 结 构 体 的 error 标 志 位 ， 
如 果 error 为 1 表示 请 求 出 错 ， 那 么 直接 返回 NGX_ERROR。 


2) 找到 请 求 的 ngx_http_request_t 结 构 体 中 存放 的 等 待 发 送 的 缓冲 
区 链表 out， 遍 历 这 个 ngx_chain_t 类 型 的 缓冲 区 链表 ， 计 算出 out 缓 冲 区 
共 占 用 了 多 大 的 字 节 数 ， 为 第 9 步 发 送 啊 应 做 准备 。 


人 @@ 注意 这 个 out 链 表 通 常 都 保存 着 待 发 送 的 响应 。 例 如 ， 在 调用 
ngx_http_send_headet 方 法 时 ， 如 果 HTTP 响 应 头 部 过 大 寻 致 无 法 一 次 性 
发 送 完 ， 那 么 剩余 的 响应 头 部 就 会 在 out 链 表 中 。 


结构 体 中 的 error 标 志 位 ] 
[error 标 志 位 为 1] 


[error 标 志 位 为 0] 1) 返 回 
2) 遍 历 out 缓 冲 区 计算 
剩余 响应 长 度 


3) 将 本 次 待 发 送 的 缓冲 区 添加 到 
out 尾 部 并 计算 总 长 度 
[检测 现在 的 out 缓 冲 区 是 否 完整 , 是否 有 必要 现在 就 发 送 ] 






[检查 ngx_connection_! 乡 





[out 不 完整 ， 本 次 可 不 发 送 ] 


[out 缓冲 区 完整 ] 


4 ) 取 出 配置 项 sendfile_max_chunk 





并 检查 它 是 否 大 于 out 响 应 长 度 
[检查 写 事 件 delayed 标 志 位 , 以 及 请 求 的 limit_rate 标 志 位 ] 





[limit_rate 不 为 0, 需要 限 速 ] 


[limit_rate 为 0 








6) 计 算 发 送 速 度 是 否 [delayed 为 1， 当 前 不 得 发 送 响应 ] 
超过 了 限制 
[目前 发 送 响应 的 速度 过 快 需要 减速 ] 











7) 写 事件 的 delayed 
标志 位 置 为 1 





9) 向 客户 出 发 送 缓冲 区 





二 limit_rate 标 志 位 ] 








8) 将 写 事 件 加 入 
定时 器 





[limit_rate 不 为 0, 需要 限 速 ] 







[limit_rate 为 0] 





10) 再 次 计算 发 送 速度 
是 否 超 讨 限制 


[不 需要 减速 | 
[发 送 响应 速度 过 快 需要 减速 | 







5 ) 将 buffer 标 志 位 置 为 可 写 状态 ， 
并 返回 NGX_AGAIN 





11) 将 写 事件 添加 到 
定时 器 [还 有 剩余 缓冲 区 待 发 送 ] 





\V 
12) 重 置 out 绥 冲 区 ， 


下 有 毕 ] [发 送 完 第] 一 13) 运 辑 
了 © 


图 11-20 ngx_http_wtite_filtet 方 法 的 流程 图 





3) ngx_http_write_filter 方 法 的 第 2 个 参数 ip 就 是 本 次 要 发 送 的 缓冲 
区 链表 ( 正 是 由 HTTP 模 块 构造 、 传 递 ) ， 本 步 又 将 类 似 第 2 步 退 历 这 个 
ngx_chain_t 类 型 的 缓存 链表 in， 将 im 中 的 缓冲 区 加 入 到 out 链 表 的 末尾 ， 
并 计算 out 缓 冲 区 共 占 用 多 大 的 字 节 数 ， 为 第 9 步 发 送 啊 应 做 准备 。 


在 第 2、 第 3 步 的 志 历 过 程 中 ， 会 检查 缓冲 区 中 每 个 ngx_buf t 抉 的 3 
个 标志 位 : flush、recycled、last_buf， 如 果 这 3 个 标志 位 同时 为 0〈( 即 竺 
发 送 的 out 链 表 中 没有 一 个 缓冲 区 表示 响应 已 经 结束 或 需要 立刻 发 送出 
去 ) ， 而 且 本 次 要 发 送 的 缓冲 区 ip 虽然 不 为 室 ， 但 以 上 两 步骤 中 计算 出 
的 待 发 送 响应 的 大 小 又 小 于 配置 文件 中 的 postpone_output 参 数 ， 那 么 说 
明 当 前 的 缓冲 区 是 不 完整 的 且 没 有 必要 立刻 发 送 ， 于 是 跳 到 第 13 步 直接 
返回 NGX_OK。 








4) 取出 nginx.conf 文 件 中 匹配 请 求 的 sendfile_max_chunk 配 置 项 (如 
它 属于 某 个 location 块 下 的 配置 项 ) ， 为 第 9 步 计算 发 送 啊 应 的 速度 做 准 
备 。 





首先 检查 连接 上 写 事 件 的 标志 位 delayed， 如 果 delayed 为 1， 则 表示 
这 一 次 的 epoll 调 度 中 请 求 仍 需 要 减速 ， 是 不 可 以 发 送 响 应 的 ，delayed 为 
1 指明 了 响应 需要 延迟 发 送 ， 这 时 跳 到 第 5 步 执 行 ， 如 果 delayed 为 0， 表 
示 本 次 不 需要 减速 ， 那 么 再 检查 ngx_http_request_t 结 构 体 中 的 limit_rate 








发 送 响应 的 速率 ， 如 果 1limit_rate 为 0， 表 示 这 个 请 求 不 需要 限制 发 送 速 
度 ， 直 接 跳 到 第 9 步 执行 ， 如 果 1limit_rate 大 于 0， 则 说 明 发 送 响应 的 速度 
不 能 超过 limit_rate 指 定 的 速度 ， 这 时 跳 到 第 6 步 执 行 。 


5) 将 客户 端 对 应 的 ngx_connection_t 结 构 体 中 的 buffered 标 志 位 放 上 
NGX_HTTP WRITE BUFFERED 安 ， 同 时 返回 NGX_AGAIN， 这 是 在 
告诉 HTTP 框 架 out 缓 冲 区 中 还 有 啊 应 等 待 发送。 


6) ngx_http_request_t 结 构 体 中 的 limit_rate 成 员 表 示 发 送 响应 的 最 大 
速率 ， 当 它 大 于 0 时 ， 表 示 需 要 限 速 ， 首 移 需 要 计算 当前 请 求 的 发 送 速 
度 是 否 已 经 达到 限 速 条 件 。 





这 里 需要 解释 第 2 章 中 介绍 过 的 nginx.conf 文 件 里 的 两 个 配置 项 : 
limit_rate 和 1limit_rate_after。limit_rate 表 示 每 秒 可 以 发 送 的 字 节 数 ， 超 过 
这 个 数字 就 需要 限 速 ， 然而， 限 速 这 个 动作 必须 是 在 发 送 了 
limit_rate_after 字 节 的 响应 后 才能 生效 (对 于 小 响应 包 的 优化 设计 )。 
下 和 面 看 看 这 一 步 是 如 何 使 用 这 两 个 配置 项 来 计算 限 速 的 ， 如 下 所 示 。 








limit = r->limit_ rate * (ngx time() - r->start_ sec + 1) 
- (c->sent - clcf->limit_rate after); 





第 9 章 已 介绍 过 ngx_time() 方 法 ， 它 取出 了 当前 时 间 ， 而 start_sec 表 
示 开 始 接收 到 客户 端 请 求 内 容 的 时 间 ，c->sent 表 示 这 条 连接 上 已 经 发 送 
了 的 HTTP 啊 应 长 度 ， 这 样 计算 出 的 变量 limit 就 表示 本 次 可 以 发 送 的 字 


节 数 了 。 如 果 limit 小 于 或 等 于 0， 它 表示 这 个 连接 上 的 发 送 响应 速度 已 
经 超出 了 limit_rate 配 置 项 的 限制 ， 所 以 本 次 不 可 以 继续 发 送 ， 跳 到 第 7 
步 执 行 ， 如 果 1limit 大 于 0， 表 示 本 次 可 以 发 送 limit 字 节 的 啊 应 ， 那 么 跳 
到 第 9 步 开 始 发 送 响应 。 


7) 由 于 达到 发 送 响 应 的 速度 上 限 ， 这 时 将 连接 上 写 事件 的 delayed 
标志 位 置 为 1。 


8) 将 写 事 件 加 入 定时 器 中 ， 其 中 超时 时 间 要 根据 第 7 步 算 出 的 limit 
来 计算 ， 如 下 所 示 : 


ngx_add_ timer(c->write, (ngx_msec_t) (- limit * 1000 / r->limit_rate + 1)); 


limit 是 已 经 超 发 的 字 节 数 ， 它 是 0 或 者 负数 。 这 个 定时 器 的 超时 时 
间 是 超 发 字 布 数 按照 limit_rate 速 率 算 出 需要 等 竺 的 时 间 再 加 上 1 坚 秒 ， 
它 可 以 使 Nginx 定 时 器 准确 地 在 允许 友 送 啊 应 时 激活 请 求 。 之 后 转 到 第 5 


步 执行 。 





9) 本 步 将 把 响应 发 送 给 客户 端 。 然 而 ， 组 冲 区 中 的 响应 可 能 非常 

那么 这 一 次 应 该 发 送 多 少 字 节 呢 ? 这 要 根据 第 6 步 计 算出 的 limit 变 

量 ， 以 及 第 4 步 取得 的 配置 项 sendfile_max_chunk 来 计算 ， 同 时 要 根据 第 
2、 第 3 步 过 历 缓 冲 区 计算 出 的 符 发 送 字 节 数 来 决定 ， 这 3 个 值 中 的 最 小 

值 即 作为 本 次 发 送 的 啊 应 长 度 。 





+ 











发 送 响 应 后 再 次 检查 请 求 的 limit_rate 标 志 位 ， 如 果 limit_rate 为 0， 
则 表示 不 需要 限 速 ， 跳 到 第 12 步 执行 ， 如 果 limit_rate 大 于 0， 则 表示 和 需 
要 限 速 ， 跳 到 第 10 步 执行 。 











10) 再 次 按照 第 6 步 中 的 方法 计算 刚 友 送 了 部 分 啊 应 后 ， 请 求 的 发 
送 速 京 是 否 达 到 ]imit_rate 上 限 ， 如 果 不 需 要 减速 就 直接 跳 到 第 12 步 ， 合 


则 继续 执行 第 11 步 。 











11) 这 时 表示 第 9 步 发 送 的 啊 应 速度 还 是 过 快 了 ， 已 经 超 发 了 一 些 
叮 应 ， 那 么 这 里 类 似 第 8 步 ， 计 算出 至 少 要 经 过 多 少 坚 秒 后 才 可 以 继续 
发 送 ， 调 用 ngx_add_timer 方 法 将 写 事件 按照 上 面 计 算出 的 又 秒 作为 超时 
时 间 添 加 到 定时 露 中。 同时， 把 写 事件 的 delayed 标 志 位 置 为 1。 





12) 重 置 ngx_http_request_t 绪 构 体 的 out 绥 冲 区 ， 把 已 经 发 送 成 功 的 
缓冲 区 归还 给 内 存 池 。 如 果 out 链 表 中 还 有 剩余 的 没有 发 送出 去 的 缓冲 
区 ， 则 添加 到 out 链 表 头 部 ， 跳 到 第 5 步 执行 ， 如 果 已 经 将 out 链 表 中 的 所 
有 缓冲 区 都 发 送 给 客户 端 了 ， 则 执行 第 13 步 。 

13) 返回 NGX_OK 表 示 成 功 。 

以 上 较为 详尽 地 描述 了 负责 实际 发 送 啊 应 的 ngx_http_write_filter 方 
法 是 怎样 工作 的 ， 包 括 如 何 更 新 请 求 里 的 out 缓 冲 区 ， 如 何 根据 限 速 条 


件 以 及 配置 文件 中 的 sendfile_ max_chunk 参 数 决定 一 次 可 以 发 送 多 少 字 
节 的 啊 应 。 





ngx_http_send_header 方 法 最 终 会 调用 ngx_http_write_filter 方 法 来 发 
送 响应 头 部 ， 而 ngx_http_output_filter 方 法 最 终 也 是 调用 
ngx_http_write_filter 方 法 来 发 送 啊 应 包 体 的 ， 同 样 ， 
ngx_http_output_filter 也 有 可 能 得 到 返回 值 NGX_AGAIN (图 11-20 的 第 5 
步 ) ， 它 表示 还 有 未 发 送 的 啊 应 缓冲 区 在 out 成 员 中 。 这 时 ， 需 要 以 
NGX_AGAIN 作 为 参数 调用 ngx_http_finalize_request 方 法 ， 该 方法 将 把 
写 事件 的 回调 方法 设 为 ngx_http_writer 方 法 ， 并 由 它 来 把 剩 下 的 响应 全 
部 发 送 给 客户 端 。 





11.9.3 ngx_http_writer 





本 节 介 绍 的 ngx_http_writer 方 法 对 各 个 HTTP 模 块 而 言 是 不 可 见 的 ， 
但 实际 上 它 非常 重要 ， 因 为 无 论 是 ngx_http_send_header 还 是 
ngx_http_output_filter 方 法 ， 它 们 在 调用 时 一 般 都 无 法 发 送 全 部 的 啊 应 ， 
剩 下 的 响应 内 容 都 得 靠 ngx_http_writer 方 法 来 发 送 。 如 何 把 
ngx_http_writer 方 法 设置 为 请 求 写 事件 的 回调 方法 呢 ? 这 部 分 内 容 将 在 
11.10.6 节 中 介绍 ， 此 处 关注 的 重点 是 ngx_http_writer 方 法 在 后 台 究 竟 做 
了 些 什 么 。 图 11-21 是 ngx_http_writer 方 法 的 流程 图 ， 如 果 这 个 请 求 的 连 
接 上 可 写 事 件 被 触发 ， 也 束 是 TCP 的 滑动 窗口 在 告诉 Nginx 进 程 可 以 发 
送 响 应 了 ， 这 时 ngx_http_writer 方 法 就 开始 工作 了 。 











[检查 写 事件 的 timedout 标志 位 , 确定 发 送 响应 是 否 超 时 ] 





[timedout 为 1, 写 事 件 超 时 , 再 检查 写 事件 的 delayed 标志 位 ] 
[delayed 为 0 请 求 没 有 限 速 > 所 以 这 里 是 真实 的 发 送 响 应 超时 ] 


[timedout 为 0, 写 事件 未 超时 ] 2 
[delayed 为 1, 这 里 的 超时 是 由 请 求 限 速 导致 ] 











2 ) 置 写 事 件 的 timedout、 





1) 结束 请 求 并 返回 


delayed 标志 位 为 0 


[检查 写 事件 的 ready 标 志 位 ] 408 响应 码 





[ready 为 0] 





[ready 为 1, 连接 上 可 以 发 送 TCP 流 ] 


>( 3 ) 将 写 事 件 加 入 定时 器 中 
5 ) 调用 ngx_http_output_filter 
方法 发 送 响应 


4) 将 写 事件 加 入 到 epoll 
[检查 发 送 啊 应 后 的 ngx_http_requestt 结构 体 状态 ] 


[out 缓 冲 区 中 仍 有 未 发 送 的 响应 ] 









[out 缓 冲 区 中 的 响应 全 部 发 送 完毕 ] 





6 ) 重 置 write _event_handler 方 法 


7) 调用 ngx_http_finalize _request 





方法 结束 请 求 


多 


图 11-21 ngx_http_wtitet 方 法 的 流程 图 


下 面 将 详细 介绍 图 11-21 中 的 7 个 步骤 。 


1) 首先 检查 连接 上 写 事 件 的 timedout 标 志 位 ， 如 果 timedout 为 0， 则 
表示 写 事 件 未 超时 ， 跳 到 第 5 步 执行 ， 如 果 timedout 为 1， 则 表示 当前 的 
写 事 件 已 经 超时 ， 这 时 有 两 种 可 能 性 ; 第 一 种 ， 由 于 网 络 异常 或 者 客户 
端 长 时 间 不 接收 响应 ， 导 致 真实 的 发 送 响应 超时 ， 第 二 种 ， 由 于 上 一 次 
发 送 响应 时 发 送 速率 过 快 ， 超 过 了 请 求 的 limit_rate 速 率 上 限 ， 而 上 节 的 
ngx_http_write_filter 方 法 就 会 设置 一 个 超时 时 间 将 写 事 件 添加 到 定时 器 
中 ， 这 时 本 次 的 超时 只 是 由 限 速 导 致 ， 并 非 真正 超时 《结合 图 11-20 理 
解 ) 。 那 么 ， 如 何 判 断 这 个 超时 是 真 的 超时 还 是 出 于 限 速 的 考虑 呢 ? 这 
要 看 事件 的 delayed 标 志 位 。 从 图 11-20 中 可 以 看 出 ， 如 果 是 限 速 把 写 事 
件 加 入 定时 器 ， 一 定 会 把 delayed 标 志 位 置 为 1， 如 其 中 的 第 7 步 和 第 11 
步 。 如 果 写 事件 的 delayed 标 志 位 为 0， 那 就 是 真 的 超时 了 ， 这 时 调用 
ngx_http_finalize_request 方 法 结束 请 求 ， 传 入 的 参数 是 
NGX_HTTP_REQUEST_TIME_OUT， 表 示 需 要 向 客户 端 发 送 408 错 误 
码 ; 如 果 delayed 标 志 位 为 1， 则 继续 执行 第 2 步 。 




















2) 既然 当前 事件 的 超时 是 由 限 速 引起 的 ， 那 么 此 时 可 以 把 写 事件 
的 timedout 标 志 位 和 delayed 标 志 位 都 重 置 为 0。 





再 检查 写 事件 的 ready 标 志 位 ， 如 果 为 1， 则 表示 在 与 客户 端的 TCP 
连接 上 可 以 发 送 数据 ， 跳 到 第 5 步 执行 ， 如 果 为 0， 则 表示 和 暂 不 可 发 送 数 
据 ， 跳 到 第 3 步 执行 。 





3) 将 写 事件 添加 到 定时 器 中 ， 这 里 的 超时 时 间 就 是 配置 文件 中 的 


send_timeout 参 数 ， 与 限 速 功能 无 关 。 


4) 调用 ngx_handle_write_event 方 法 将 写 事件 添加 到 epoll 等 事件 收 
集 器 中 ， 同 时 ngx_http_writer 方 法 结束 。 


5) 调用 ngx_http_output_filter 方 法 发 送 响应 ， 其 中 第 2 个 参数 〈 也 就 
是 表示 需要 发 送 的 缓冲 区 ) 为 NULL 指 针 。 这 意味 着 ， 需 要 调用 各 包 体 
过 滤 模 块 处 理 out 绥 冲 区 中 的 剩余 内 容 ， 最 后 调用 ngx_http_write_filter 方 
法 把 响应 发 送出 去 。 








发 送 响 应 后 ， 查 看 ngx_http_request_t 结 构 体 中 的 buffered 和 
postponed 标 志 位 ， 如 果 任 一 个 不 为 0， 则 意味 着 没有 发 送 完 out 中 的 全 部 
响应 ， 这 时 跳 到 第 3 步 执 行 ， 请 求 main 指 针 指 向 请 求 自身 ， 表 示 这 个 请 
求 是 原始 请 求 ， 再 检查 与 客户 端 间 的 连接 ngx_connection_t 结 构 体 中 的 
buffered 标 志 位 ， 如 果 buffered 不 为 0， 同 样 表示 没有 发 送 完 out 中 的 全 部 
响应 ， 仍 然 跳 到 第 3 步 执行 ， 除 此 以 外 ， 都 表示 out 中 的 全 部 响应 皆 发 送 


完毕 ， 跳 到 第 6 步 执行 。 




















6) 将 请 求 的 write_event_handler 方 法 置 为 
ngx_http_request_empty_handler， 也 就 是 说 ， 如 果 这 个 请 求 的 连接 上 再 
有 可 写 事 件 ， 将 不 做 任何 处 理 。 


7) 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 其 中 第 2 个 参数 传 


入 的 是 ngx_http_output_filter 方 法 的 返回 值 。 


从 注意 ng htp_writer 方 法 仅 用 于 在 后 台 发 送 响应 到 客户 端 


11.10 结束 HTTP 请 求 


对 于 事件 驱动 的 架构 来 说 ， 结 束 请 求 是 一 项 复杂 的 工作 。 因 为 一 个 
请 求 可 能 会 被 许多 个 事件 触发 ， 这 使 得 Nginx 框 架 调 度 到 茶 个 请 求 的 回 
调 方法 时 ， 在 当前 业务 内 似乎 需要 结束 HTTP 请 求 ， 但 如 果真 的 结束 了 
请 求 ， 销 毁 了 与 请 求 相关 的 内 存 ， 多 半 会 造成 重大 错误 ， 因 为 这 个 请 求 
可 能 还 有 其 他 事件 在 定时 器 或 者 epol 中 。 当 这 些 事件 被 回调 时 ， 请 求 却 
己 经 不 存在 了 ， 这 就 是 严重 的 内 存 访问 越界 错误 ! 如 果 稚 试 在 属于 某 个 
HTTP 模 块 的 回调 方法 中 试图 结束 请 求 ， 先 要 把 这 个 请 求 相关 的 所 有 事 
件 〈 有 些 事件 可 能 属于 其 他 HITP 模 其 ) 都 从 定时 髓 和 epoll 中 取出 并 调 
用 其 handler 方 法 ， 这 又 太 复 如 了 ， 男 外 ， 不 同 HTTP 模 块 上 的 代码 灶 合 
太 紧 密 将 会 难以 维护 。 











那 HTTP 框 染 义 是 怎样 解决 这 个 问题 的 呢 ? HITP 框 以 把 一 个 请 求 分 
为 多 种 动作 ， 如 果 HTTP 框 染 提 供 的 方法 会 导致 Nginx 再 次 调度 到 请 求 
(例如 ， 在 这 个 方法 中 产生 了 新 的 事件 ， 或 者 重新 将 已 有 事件 添加 到 
epoll 或 者 定时 器 中 ) ， 那 么 可 以 认为 这 一 步调 用 是 一 种 独立 的 动作 。 例 
如 ， 接 收 HTTP 请 求 的 包 体 、 调 用 upstream 机 制 提供 的 方法 访问 第 三 方 服 
务 、 派 生出 subrequest 子 请 求 等 。 这 些 所 谓 独立 的 动作 ， 都 是 在 告诉 
Nginx， 如 末 机 会 合适 就 再 次 调用 它们 处 理 请 求 ， 因 为 这 个 动作 并 不 是 
Nginx 调 用 一 次 它们 的 方法 就 可 以 处 理 完 毕 的 。 因 此 ， 每 一 种 动作 对 于 








整个 请 求 来 说 都 是 独立 的 ，HTTP 框 架 希 望 每 个 动作 结束 时 仪 维护 自己 
的 业务 ， 不 用 去 关心 这 个 请 求 是 否 还 做 了 其 他 动作 。 这 种 设计 大 大 降低 
了 复杂 度 。 


这 种 设计 具体 又 是 怎么 实现 的 呢 ? 实际 上 ， 在 11.8 节 中 己 经 介绍 
过 ， 每 个 HITP 请 求 都 有 一 个 引用 计数 ， 每 派生 出 一 种 新 的 会 独立 向 事 
件 收 集 器 注册 事件 的 动作 时 〈 如 ngx_http_read_client_request_body 方 法 
或 者 ngx_http_subrequest 方 法 ) ， 都 会 把 引用 计数 加 1， 这 样 每 个 动作 结 
束 时 都 通过 调用 ngx_http_finalize_request 方 法 来 结束 请 求 ， 而 
ngx_http_finalize_request 方 法 实际 上 却 会 在 引用 计数 减 1 后 先 检查 引用 计 
数 的 值 ， 如 果 不 为 0 是 不 会 真正 销毁 请 求 的 。 














也 就 是 说 ，HTTP 框 架 要 求 在 请 求 的 茶 个 动作 结束 时 ， 必 须 调 用 
ngx_http_finalize_request 方 法 来 结束 请 求 。ngx_http_finalize_request 方 法 
也 设计 得 比较 复杂 ， 在 第 3 章 中 曾经 谈 到 过 它 最 基本 的 用 法 ， 本 市 中 将 
详细 讨论 ngx_http_finalize_request 方 法 到 底 做 了 些 什么 。 


在 说 明 ngx_http_finalize_request 方 法 前 ， 先 介绍 一 下 HTTP 框 架 提供 
的 几 个 更 低级 别 的 结束 请 求 方法 。 


11.10.1 ngx_http_close_connection 


ngx_http_close_connection 方 法 是 HTTP 框 染 提 供 的 一 个 用 于 释放 





TCP 连 接 的 方法 ， 它 的 目的 很 简单 ， 束 是 关闭 这 个 TCP 连 接 ， 当 且 仅 当 
HTTP 请 求 真 正 结束 时 才 会 调用 这 个 方法 。 图 11-22 列 出 了 
ngx_http_close_connection 方 法 所 做 的 工作 。 


1 ) 将 连接 的 读 / 写 事件 





从 是 时 融 中 取出 


7) 将 连接 的 读 主 事件 从 
epoll 中 取出 





3 ) 将 描述 连接 的 ngx_connection 
结构 体 释 放 到 空闲 连接 池 


4) 关闭 TCP 


连接 


AT 上 tL vA 上 四 
5 ) 销毁 连接 ngx_connection_ 1 


中 的 内 存 池 
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图 11-22 ngx_http_close_connection 方 法 的 流程 图 


下 面 先 来 分 析 一 下 这 个 底层 的 方法 ngx_http_close_connection 究 竟 做 


fs 


1) 首先 将 连接 的 读 / 写 事件 从 定时 器 中 取出 。 实 际 上 就 是 检查 读 / 写 
事件 的 time_set 标 志 位 ， 如 果 为 1， 则 证 明 事 件 在 定时 器 中 ， 那 么 需要 调 
用 ngx_del_timer 方 法 把 事件 从 定时 器 中 移 除 。 


2) 调用 ngx_del_conn 宏 (或 者 ngx_del_event 宏 ) 将 读 / 写 事件 从 
epoll 中 移 除 。 实 际 上 就 是 调用 第 9 章 重 点 介绍 过 的 ngx_event_actions_t 接 
口中 的 del_conn 方 法 ， 当 事件 模块 是 epoll 模 块 时 ， 就 是 从 epol 中 移 除 这 
个 连接 的 读 / 写 事件 。 同 时 ， 如 果 这 个 事件 在 ngx_posted_accept_events 或 
者 ngx_posted_events 队 列 中 ， 还 需要 调用 ngx_delete_posted_event 宏 把 事 
件 从 post 事 件 队 列 中 移 除 。 


3) 调用 ngx_free_connection 方 法 把 表示 连接 的 ngx_connection_t 结 构 
体 归 还 给 ngx_cycle_t 核 心 结构 体 的 空闲 连接 池 free_connections。 


4) 调用 系统 提供 的 dose 方 法 关闭 这 个 TCP 连 接 套 接 字 。 
5) 销毁 ngx_connection_t 结 构 体 中 的 pool 内 存 池 。 
可 见 ， 这 个 ngx_http_close_connection 方 法 主要 是 针对 连接 做 了 一 些 


工作 ， 它 是 非 第 基础 的 方法 。 


11.10.2 ngx_http_free_request 


ngx_http_free_request 方 法 将 会 释放 请 求 对 应 的 ngx_http_request_t 数 
据 结 构 ， 它 并 不 会 像 ngx_http_close_connection 方 法 一 样 去 释放 承载 请 求 
的 TCP 连 接 ， 每 一 个 TCP 连 接 可 以 反复 地 承载 多 个 HTTP 请 求 ， 因 此 ， 
ngx_http_free_request 是 比 ngx_http_close_connection 更 高 层次 的 方法 ， 前 
者 必然 先 于 后 者 调用 。 下 面 看 看 图 11-23 中 ngx_http_free_request 方 法 到 
谨 做 了 哪些 工作 。 


在 描述 图 11-23 之 前 ， 先 来 看 一 个 数据 结构 ngx_http_cleanup_t， 它 
的 定义 如 下 。 
















1 ) 调用 请 求 cleanup 
链表 内 的 方法 做 清理 工作 







2 ) 调用 NGX_HTTP LOG_PHASE 
阶段 的 回调 方法 记录 日 志 









和 


请 求 ngx_http_request_t 


中 的 内 存 池 





3 ) 销毁 


图 11-23 ngx_http_free_request 方 法 的 流程 图 





typedef struct ngx_http_cleanup_s ngx_http_cleanup_t; 
struct ngx_http_cleanup_s { 
// 由 


HTTP 模 块 提供 的 清理 资源 的 回调 方法 


ngx_http_cleanup_pt handler; 
// 希望 给 上 面 的 


handler 方 法 传递 的 参数 


void *data; 
/* 一 个 请 求 可 能 会 有 多 个 


ngx_http_cleanup_t 清 理 方 法 ， 这 些 清理 方法 间 就 是 通过 


next 指 针 连 接 成 单 链表 的 


*/ 
ngx_http_cleanup_t *next,; 


了 





事实 上 ， 任 何 一 个 请 求 的 ngx_http_request_t 结 构 体 中 都 有 一 个 
ngx_http_cleanup_t 类 型 的 成 员 cleanup， 如 果 没 有 需要 清理 的 资源 ， 则 
cleanup 为 空 指 针 ， 否 则 HTTP 模 块 可 以 同 cleanup 中 以 单 链表 的 形式 无 限 
制 地 添加 ngx_http_cleanup_t 结 构 体 ， 用 以 在 请 求 结束 时 释放 资源 。 再 看 
看 handler 方 法 的 定义 ， 如 下 所 示 。 











typedef void (*ngx_http_cleanup_pt)(void *data); 





如 有 果 需 要 在 请 求 释放 时 执行 一 些 回 调 方 法 ， 首 先 需 要 实现 一 个 
ngx_http_cleanup_pt 方 法 。 当 然 ，HTTP 框 架 还 很 友好 地 提供 了 一 个 工具 
方法 ngx_http_cleanup_add， 用 于 癌 请 求 中 添加 ngx_http_dleanup_t 结 构 
体 ， 其 定义 如 下 。 





ngx_http_cleanup_t * ngx_http_cleanup_add(ngx_http_request t *r, Size t size) 





这 个 方法 返回 的 束 是 已 经 插入 请 求 的 ngx_http_cleanup_t 结 构 体 指 








针 ， 其 中 data 成 员 指 向 的 内 存 都 已 经 分 配 好 ， 内 存 的 大 小 由 Size 参数 指 


me 


人 和。 


@@ ij: 意 。 事实 上 ， 在 3.8.2 节 中 曾经 简单 地 介绍 过 同样 用 于 清理 次 
源 的 ngx_pool_cleanup_t， 它 与 ngx_http_cleanup_pt 是 不 同 的 ， 
ngx_bool cleanup_t 仅 在 所 用 的 内 存 池 销毁 时 才 会 被 调用 来 清理 资源 ， 它 
何 时 释放 资源 将 视 所 使 用 的 内 存 池 而 定 ， 而 ngx_http_cleanup_pt 是 在 
ngx_http_request_t 结 构 体 释放 时 被 调用 来 释放 资源 的 。 


下 面 说 明 一 下 ngx_http_free_request 方 法 所 做 的 3 项 主要 工作 。 


1) 循环 地 遍历 请 求 ngx_http_request_t 结 构 体 中 的 cleanup 链 表 ， 依 
次 调用 每 一 个 ngx_http_cleanup_pt 方 法 释放 资源 。 


2) 在 11 个 ngx_http_phases 阶 段 中 ， 最 后 一 个 阶段 叫做 
NGX_HTTP_LOG_PHASE， 它 是 用 来 记录 客户 端的 访问 日 志 的 。 在 这 
一 步骤 中 ， 将 会 依次 调用 NGX_HTTP_ LOG_PHASE 阶 段 的 所 有 回调 方 
法 记录 日 志 。 官 方 的 ngx_http_log_module 模 块 就 是 在 这 里 记录 access log 
的 。 











3) 销毁 请 求 ngx_http_request_t 结 构 体 中 的 pool 内 存 池 。 在 销毁 内 存 
池 时 ， 挂 在 该 内 存 池 下 的 由 各 Nginx 模 块 实现 的 ngx_pool_cleanup_t 方 法 
也 会 被 调用 ， 注 意 它 与 第 1 步 的 区 别 。 





@ 注意 ”如果 打开 了 统计 HTIP 请 求 的 功能 ， ngx_http_free_request 
方法 还 会 更 新 共享 内 存 中 的 统计 请 求 数 量 的 两 个 原子 变量 : 


ngx_stat_reading、ngx_stat_writing， 详 见 14.2.1 节 。 


11.10.3 ngx_http_close_request 








ngX_http_close_request 方 法 是 更 高 层 的 用 于 关闭 请 求 的 方法 ， 当 
然 ，HTTP 模 块 一 般 也 不 会 直接 调用 它 的 。 在 上 面 几 节 中 反复 提 到 的 引 
用 计数 ， 就 是 由 ngx_http_close_request 方 法 负责 检测 的 ， 同 时 它 会 在 引 
用 计数 清 零 时 正式 调用 ngx_http_free_request 方 法 和 
ngx_http_close_connection 方 法 来 释放 请 求 、 关 闭 连 接 。 先 来 看 看 图 11- 
24 中 列 出 的 ngx_http_close_request 方 法 所 做 的 工作 。 





1 ) 对 应 的 原始 请 求 的 
引用 计数 减 1 
| 检查 原始 请 求 的 count 引 用 计数 值 和 block 标 志 位 |] 











count 等 于 0 日 blocked 为 01 





2 ) 调用 ngx_http_free _ request 方法 


count 大 于 0 或 者 block 大 于 0] 


3 ) 调 上 和 nex hi Ui lose_connection 方 法 


图 11-24 ngx_http_close_request 方 法 的 流程 图 


下 面 简单 说 明 一 下 ngx_http_close_request 方 法 所 做 的 工作 。 


1) 首先 ， 由 ngx_http_request_t 结 构 体 的 main 成 员 中 取出 对 应 的 原 
始 请 求 〈 当 然 ， 可 能 就 是 这 个 请 求 本 身 ) ， 再 取出 count 引 用 计数 并 减 
1。 然 后 ， 检 查 count 引 用 计数 是 否 已 经 为 0， 以 及 blocked 标 志 位 是 否 关 
0。 如 果 count 已 经 为 0， 则 证 明 请 求 没 有 其 他 动作 要 使 用 了 ， 同 时 
blocked 标 志 位 也 为 0， 表 示 没 有 HTTP 模 块 还 需要 处 理 请 求 ， 所 以 此 时 请 
求 可 以 真正 释放 ， 这 时 跳 到 第 2 步 执行 ， 如 果 count 引 用 计数 大 于 0， 或 
者 blocked 大 于 0， 这 样 都 不 可 以 结束 请 求 ，ngx_http_close_request 方 法 直 
接 结束 。 


2) 调用 ngx_http_free_request 方 法 释放 请 求 。 
3) 调用 ngx_http_close_connection 方 法 关闭 连接 。 


人 注意 在 官方 发 布 的 HTTP 模 块 中 ，ngx_http_request_t 结 构 体 中 
的 blocked 标 志 位 主要 由 异步 I/O 使 用 ，ngx_http_close_fequest 方 法 正 是 通 
过 blocked 配 合 着 异步 I/O 工 作 ， 如 果 AIO 上 下 文中 还 在 处 理 这 个 请 求 ， 
blocked 必 然 是 大 于 0 的 ， 这 时 npgx_http_close_fequest 方 法 不 能 结束 请 求 。 


由 于 本 章 不 涉及 异步 AIO ， 所 以 略 过 不 提 。 
11.10.4 ngx_http_ finalize_connection 


ngx_http_finalize_connection 方 法 虽然 比 ngx_http_close_request 方 法 


高 了 一 个 层次 ， 但 HITP 模 块 一 般 还 是 不 会 直接 调用 它 。 


ngx_http_finalize_connection 方 法 在 结束 请 求 时 ， 解 决 了 keepalive 特 性 和 
子 请 求 的 问题 ， 图 11-25 中 展示 了 它 所 做 的 工作 。 


下 面 简单 分 析 一 下 ngx_http_finalize_connection 方 法 所 做 的 工作 。 








1) 首先 查看 原始 请 求 的 引用 计数 ， 如 果 不 等 于 1， 则 表示 还 有 多 个 
动作 在 操作 着 请 求 ， 接 着 继续 检查 discard_body 标 志 位 。 如 果 
discard_body 为 0， 则 直接 跳 到 第 3 步 ， 如 果 discard_body 为 1， 则 表示 正 
在 丢弃 包 体 ， 这 时 会 再 一 次 把 请 求 的 read_event_handler 成 员 设 为 
ngx_http_discarded_request_body_handler 方 法 ， 就 如 同 11.8.2 节 中 描述 的 
一 样 。 


[ 检查 原始 请 求 的 count 引用 计数 ] 





[count 不 等 于 1, 检查 discard_body 标志 位 请 求 是 否 正 丢弃 包 体 | 





[discard_body 为 1] 





1 ) 为 丢弃 包 体 设置 读 [count 为 1, 检查 keepalive 标志 位 ] 
事件 处 理 方法 


[discard body 为 0] 
2) 将 读 事件 添加 到 
定时 器 中 


[keepalive 为 0, 检查 是 否 需要 延迟 关闭 请 求 ] 





[不 需要 延迟 关闭 请 求 ] 
[需要 延迟 关闭 请 求 ] 


3 ) 调 用 ngx_http_close_request 
方法 结束 请 求 [keepalive 为 1, 请 求 基 于 keep -alive 连 接 ] 





4) 调 用 ngx_http_set_lingering_close 


方法 延迟 关闭 


5 ) 调 用 ngx_http_set_keepalive 
方法 设置 keepalive 连 接 





图 11-25 ”ngx_http_finalize_connection 方 法 的 流程 


如 果 引 用 计数 为 1， 则 说 明 这 时 要 真 的 准备 结束 请 求 了 。 不 过 ， 还 


要 检查 请 求 的 keepalive 成 员 ， 如 果 keepalive 为 1， 则 说 明 这 个 请 求 需要 释 
放 ， 但 TCP 连 接 还 是 要 复 用 的 ， 这 时 跳 到 第 5 步 执 行 ， 如 果 keepalive 为 0 
就 不 需要 考虑 keepalive 请 求 了 ， 但 还 需要 检测 请 求 的 lingering_close 成 
员 ， 如 果 lingering_close 为 1， 则 说 明 需 要 延迟 关闭 请 求 ， 这 时 也 不 能 
的 去 结束 请 求 ， 而 是 跳 到 第 4 步 ， 如 果 lingering_close 为 0， 才 真 的 跳 到 第 
5 步 结 束 请 求 。 





2) 将 读 事件 添加 到 定时 器 中 ， 其 中 超时 时 间 是 lingering_timeout 配 
置 项 。 


3) 调用 11.10.3 节 介绍 的 ngx_http_close_request 方 法 结束 请 求 。 


4) 调用 ngx_http_set_lingering_close 方 法 延迟 关闭 请 求 。 实 际 上 ， 
这 个 方法 的 意义 束 在 于 把 一 些 必须 做 的 事情 做 完 〈 如 接收 用 户 端 发 来 的 
字符 流 ) 再 关闭 连接 。 


5) 调用 ngx_http_set keepalive 方 法 将 当前 连接 设 为 keepalive 状 态 。 
它 实际 上 会 把 表示 请 求 的 ngx_http_request_t 结 构 体 释放 ， 却 又 不 会 调用 
ngx_http_close_connection 方 法 关闭 连接 ， 同 时 也 在 检测 keepalive 连 接 是 
侍 超 时 ， 对 于 这 个 方法 ， 此 处 不 做 详细 解释 。 





11.10.5 ngx_http_terminate_request 


ngx_http_terminate_request 方 法 是 提供 给 HTTP 模 块 使 用 的 结束 请 求 
方法 ,但 它 属于 非 正常 结束 的 场景 ， 可 以 理解 为 强制 关闭 请 求 。 也 就 是 
说 ， 当 调用 ngx_http_terminate_request 方 法 结束 请 求 时 ， 它 会 直接 找 出 
该 请 求 的 main 成 员 指 向 的 原始 请 求 ， 并 直接 将 该 原始 请 求 的 引用 计数 置 
为 1， 同 时 会 调用 ngx_http_close_request 方 法 去 关闭 请 求 。 与 上 文 不 同 的 
是 ， 它 是 HTTP 框 架 提供 给 各 个 HTTP 模 块 直接 使 用 的 方法 ， 篇 幅 所 限 ， 
这 个 方法 就 不 再 详细 介绍 了 。 

















11.10.6 ngx_http_finalize_request 


ngx_http_finalize_request 方 法 是 开发 HTTP 模 块 时 最 常 使 用 的 结束 请 
求 方法 ， 在 第 3 章 中 早已 介绍 过 它 的 简单 用 法 。 事 实 上 ， 
ngx_http_finalize_request 方 法 被 HTTP 框 架设 计 得 极为 复杂 ， 各 种 结束 请 
求 的 场景 都 被 它 考虑 到 了 ， 下 面 将 详细 讲述 这 个 方法 究竟 做 了 些 什 么 。 
首先 回顾 一 下 它 的 定义 。 














void ngx_http_finalize request(ngx_http_request t *r, ngx_int_t rc) 








其 中 ， 参 数 r 就 是 当前 请 求 ， 它 可 能 是 派生 出 的 子 请 求 ， 也 可 能 是 
客户 端 发 来 的 原始 请 求 。 后 面 的 参数 rc 就 非常 复杂 了 ， 它 既 可 能 是 
NGX_OK、 NGX_ ERROR NGX_AGAIN、 NGX_DONE. 


NGX_DECLINED 这 种 系统 定义 的 返回 值 ， 又 可 能 是 类 似 


NGX_HTTP REQUEST_TIME_OUT 这 样 的 HTTP 响 应 码 ， 因 此 ， 
ngx_http_finalize_ request 方法 的 流程 异常 复杂 。 学 习 如 何 正 确 地 使 用 
ngx_http_finalize_request 方 法 非常 关键 ， 因 为 会 涉及 不 同 动作 导致 的 引 
用 计数 增加 、 异 常情 况 下 自动 构造 响应 、 未 发 送 完 所 有 啊 应 时 自动 同事 
件 框 架 添 加 写 事 件 回 调 方法 ngx_http_writer 等 各 种 场景 。 大 多 数 情况 
下 ， 我 们 都 会 把 其 他 Nginx 方 法 的 返回 值 作为 rc 参数 来 调用 
ngx_http_finalize_request 方 法 ， 但 如 果 要 编写 复杂 的 HTTP 模 块 ， 还 是 需 
要 清晰 地 认识 ngx_http_finalize_request 方 法 的 工作 原理 。 











下 面 把 ngx_http_finalize_request 方 法 的 主要 流程 简化 为 了 17 个 主要 
步骤 ， 如 图 11-26 所 示 。 





1 ) 检查 第 2 个 


参 2 IC 
[rc 参数 为 NGX_DECLINED] 














2 ) 设置 write_event_handler 方 法 为 
ox_1 ， hases 
[re 参数 不 是 NGX_DEGLINED 和 NGX_DONG， > 
检查 是 否 为 原始 请 求 ] 
[re 参数 为 NGX_DONE] 
[属于 subreguest 子 请 求 ] 


3) 调用 ngx_ http— core_run, _phases 
Ee 处理 请 3 





5) 调 用 post_subrequest 





的 handler 方 法 4) 调 用 ngx_http finalize_connection 


6) 再 次 检查 rc 参数 
[re 参数 为 NGX_ERROR，NGX_HTTP_REQUEST_TIME_OUT、 

< NGX_HTTP_CLIENT_CLOSED_REOUEST， 或 者 连接 错误 ] 

[re 参数 为 201 或 者 204, 以 及 re 的 值 大 于 或 等 于 300] 





方法 结束 请 求 













8) 若 为 原始 请 求 就 由 定时 器 中 
去 除 读 / 写 事件 
[re 为 其 他 值 ] 











9 Wa 事件 的 处 理 方 法 为 


tp request_handler 


pp 调用 ngx_http_terminate_request 





10) 调 用 ngx_http_special_response_handler 
方法 发 送 响 应 














11) 再 次 | Dna _request 


FR 和 下 请 
原始 请 求 

[检查 r 是 否 等 于 r> main] 

[当前 请 求 不 是 原始 请 求 ] 















13) 将 其 父 请 求 添加 到 
posted_postedrequests 链 表 中 








[当前 请 求 就 是 原始 请 求 ] 


[ou 缓冲 区 还 有 剩余 响应 ] 


[out 绥 冲 区 中 的 响应 都 已 发 送 完毕 ] 
14) 设 置 ngx_http_writer 


为 写 事件 回调 方法 





16) 由 定时 器 中 移 除 
读 / 写 事件 





VY 
15) 将 写 事件 添加 到 定时 器 


17) 调用 ngx_http_finalize_connection 
lepoll 


方法 结束 请 求 











图 11-26 ”ngx_http_finalize_request 方 法 的 流程 图 





下 面 解释 一 下 ngx_http_finalize_request 方 法 所 做 的 工作 。 





1) 首先 检查 rc 参数 。 如 果 rc 为 NGX_DECLINED， 则 跳 到 第 2 步 执 
行 ， 如 果 rc 为 NGX_DONE， 则 跳 到 第 4 步 执 行 ， 除 此 之 外 ， 都 继续 执行 


入 入 一 工 广 
于 D5 俏 。 


2) NGX_DECLINED 参 数 表 示 请 求 还 需要 按照 11 个 HTTP 阶 段 继 续 
处 理 下 去 ， 参 考 11.6 市 的 内 容 可 以 知道 ， 这 时 需要 继续 调用 
ngx_http_core_run_phases 方 法 处 理 请 求 。 这 一 步 中 首先 会 把 
ngx_http_request_t 结 构 体 的 write_event_handler 设 为 
ngx_http_core_run_phases 方 法 。 同 时 ， 将 请 求 的 content_handler 成 员 置 
为 NULL 空 指针 ，11.6 节 已 介绍 过 这 个 成 员 ， 它 是 一 种 用 于 在 


NGX_HTTP_ CONTENT PHASE 阶段 处 理 请 求 的 方式 ， 将 其 设置 为 





NULL 是 为 了 让 ngx_http_core_content_phase 方 法 〈11.6.4 节 介绍 ) 可 以 继 


续 调 用 NGX HTTP_ CONTENT PHASE 阶段 的 其 他 处 理 方法 。 


3) 调用 ngx_http_core_run_phases 方 法 继续 处 理 请 求 ， 


ngx_http_finalize_request 方 法 结束 。 


4) NGX_DONE 人 参数 表示 不 需要 做 任何 事 ， 直 接 调用 
ngx_http_finalize_connection 方 法 ， 之 后 ngx_http_finalize_request 方 法 结 
束 。 当 某 一 种 动作 〈 如 接收 HTTP 请 求 包 体 ) 正常 结束 而 请 求 还 有 业务 
要 继续 处 理 时 ， 多 半 都 是 传递 NGX_DONE 参 数 。 由 11.10.4 节 我 们 知 





道 ， 这 个 ngx_http_finalize_connection 方 法 还 会 去 检查 引用 计数 情况 ， 并 
二 


定 会 销毁 请 求 。 








5) 检查 当前 请 求 是 否 为 subrequest 子 请 求 ， 如 果 不 是 ， 则 跳 到 第 6 
步 执 行 ， 如 果 是 子 请 求 ， 那 么 调用 post_subrequest 下 的 handler 回 调 方 
法 。 在 第 6 章 中 曾经 介绍 过 subrequest 的 用 法 ， 可 以 看 到 post_subrequest 
正 是 此 时 被 调用 的 。 








6) 第 1 步 只 是 把 rc 参数 的 两 种 特殊 值 处 理 抒 了， 现在 又 需要 再 次 检 
查 rc 参数 了 。 如 果 rc 值 为 NGX_ERROR、 
NGX_HTTP_REQUEST_TIME_OUT、NGX_HTTP_CLOSE、 
NGX_HTTP_CLIENT_CLOSED_REQUEST， 或 者 这 个 连接 的 error 标 志 


为 1， 那 么 跳 到 第 7 步 执 行 ， 如 果 rc 为 NGX_HTTP_CREATED、 





NGX_HTTP_NO_CONTENT 或 者 大 于 或 等 于 
NGX_HTTP_SPECIAL_RESPONSE， 则 表示 请 求 的 动作 是 上 传 文件 ， 
或 者 HTTP 模 块 需要 HTTP 框 架构 造 并 发 送 啊 应 人 码 大 于 或 等 于 300 以 上 的 
特殊 啊 应 ， 这 时 路 到 第 8 步 执行 ， 其 他 情况 下 ， 直 接 跳 到 第 12 步 执行 。 


7) 这 一 步 直 接 调用 ngx_http_terminate_request 方 法 强制 结束 请 求 ， 
同时 ，ngx_http_finalize_request 方 法 结 


8) 检查 当前 请 求 的 main 是 人 否 指 问 自 己 ， 如 果 是 ， 这 个 请 求 束 是 来 
自 客户 端的 原始 请 求 〈 非 子 请 求 ) ， 这 时 检查 读 / 写 事件 的 timer_set 标 志 





位 ， 如 果 timer_set 为 1， 则 表明 事件 在 定时 器 中 ， 需 要 调用 ngx_del_timer 
方法 把 读 / 写 事件 从 定时 器 中 移 除 。 


9) 设置 读 / 写 事件 的 回调 方法 为 ngx_http_request_handler 方 法 ， 这 
个 方法 在 11.6 节 中 介绍 过 ， 它 会 继续 处 理 HTTP 请 求 。 


10) 调用 ngx_http_special_response_handler 方 法 ， 该 方法 负责 根据 rc 
参数 构造 完整 的 HITP 啊 应 。 为 什么 可 以 在 这 一 步 中 构造 这 样 的 啊 应 
呢 ? 回顾 一 下 第 7 步 ， 这 时 rc 要 么 是 表示 上 传 成 功 的 201 或 者 204， 要 人 么 
就 是 表示 异步 的 300 以 上 的 响应 码 ， 对 于 这 些 情况 ， 都 是 可 以 让 HTTP 杠 
染 独 立 构造 啊 应 包 的 。 





11) 再 次 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 不 过 这 时 的 
rc 参数 实际 上 是 第 10 步 ngx_http_special_response_handler 方 法 的 返回 值 。 





12) 再 次 检查 请 求 的 main 成 员 是 否 指 问 上 自己 ， 即 当前 请 求 是 否 为 原 
侣 请求。 如 果 不 是 客户 端 发 来 的 原始 请 求 ， 跳 到 13 步 继续 执行 ， 如 果 是 
原始 请 求 ， 那 么 还 需要 检查 out 绥 冲 区 内 是 人 否 还 有 没 发 送 完 的 啊 应 ， 如 
果 有 ， 则 跳 到 第 14 步 继续 执行 ， 如 果 没 有 ， 则 可 以 结束 请 求 了 ， 此 时 跳 


到 第 16 步 。 








13) 由 于 当前 请 求 是 子 请 求 ， 那 么 正常 情况 下 需要 跳 到 它 的 父 请 求 
上 上， 激活 父 请 求 继 续 加 下 执行 ， 所 以 这 一 步 首先 根据 ngx_http_request_t 
结构 体 的 parent 成 员 找 到 父 请 求 ， 再 构造 一 个 ngx_http_posted_request_t 


结构 体 把 父 请 求 放 置 其 中 ， 最 后 把 该 结构 体 添 加 到 原始 请 求 的 
posted_requests 链 表 中 ， 这 样 11.7 节 中 介绍 过 的 
ngx_http_run_posted_requests 方 法 就 会 在 图 11-12 描 述 的 流程 中 调用 父 请 
求 的 write_event_handler 方 法 了 。 








14) 在 11.9 节 中 多 次 讲 到 ， 当 HTTP 响 应 过 大 ， 无 法 一 次 性 发 送 给 
客户 端 时 ， 需 要 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 而 该 方法 
会 把 11.9.3 节 介绍 的 ngx_http_writer 方 法 注册 给 epoll 和 定时 器 ， 当 连接 再 
次 可 写 时 就 会 继续 发 送 剩 余 的 响应 ， 这 些 工作 就 是 在 第 14、 第 15 步 中 完 
成 的 。 这 一 步 先 把 请 求 的 write_event_handler 成 员 设 为 ngx_http_writer 方 
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15) 如 果 写 事件 的 delayed 标 志 位 为 0， 就 把 写 事件 添加 到 定时 器 
中 ， 超 时 时 间 就 是 nginx.conf 文 件 中 的 send_timeout 配 置 项 ， 当 然 ， 如 果 
delayed 为 1， 则 表示 限制 发 送 速度 ， 从 11.9.2 节 可 以 看 出 ， 在 需要 限 速 
时 ， 根 据 计 算得 到 的 超时 时 间 已 经 把 写 事件 添加 到 定时 器 中 了 。 再 调用 
ngx_handle_write_event 方 法 把 写 事件 诬 加 到 epol 中 。 








16) 到 了 这 里 真 的 要 结束 请 求 了 。 首 先 判 断 读 / 写 事件 的 timer_set 标 
志 人 位， 如果 timer_set 为 1， 则 需要 把 相应 的 读 / 写 事件 从 定时 器 中 移 除 。 





17) 调用 11.10.4 节 中 介绍 过 的 ngx_http_finalize_connection 方 法 结束 
请 求 。 


事实 上 ，ngx_http_finalize_ request 方法 的 分 支流 程 远 不 止 上 面 的 17 
步 ， 为 了 让 读者 清晰 地 理解 其 主要 工作 ， 许 多 不 太 重 要 的 分 支 都 从 图 
10-26 中 去 除了 。 到 此 ， 读 者 应 当 对 ngx_http_finalize_request 方 法 有 了 相 
当 全 面 的 了 解 ， 这 时 再 开发 HTTP 模块 就 可 以 灵活 地 指定 rc 参数 了 。 


1111 站 人 


本 章 系 统 地 介绍 了 HTTP 框 架 是 如 何 运行 的 ， 特 别 是 它 如 何 与 第 9 章 
介绍 的 事件 框架 交互 ， 以 及 如 何 与 本 书 第 二 部 分 介绍 的 普通 HTTP 模 块 
交互 。 阅 读 完 本 章 内 容 后 ， 相 信 读 者 会 对 HTTP 模 块 的 开发 有 一 个 全 新 
的 认识 ， 甚 至 对 于 在 HITP 请 求 的 处 理 过 程 中 HTTP 模块 占用 的 服务 器 资 
源 都 会 有 深入 的 了 解 ， 也 就 是 说 ， 这 时 读者 应 当 具 备 开发 复杂 的 HTTP 
模块 的 能 力 了 ， 甚 至 可 以 处 理 非 HTTP， 而 是 其 他 基于 TCP 的 应 用 层 协 
议 ， 它 们 也 可 以 仿照 HTTP 框 架 ， 定 义 一 种 新 的 模块 类 型 和 处 理 框架 ， 
从 而 高 效 地 处 理 新 业务 。 





upstream 机 制 实 际 上 也 属于 HTTP 框 架 的 内 容 ， 下 一 章 中 我 们 将 介绍 
它 的 实现 原理 。 


第 12 间 ”upstream 机 制 的 设计 与 实现 


第 5 章 中 曾经 举例 说 明 过 upstream 机 制 的 一 种 基础 用 法 ， 本 章 将 讨论 
upstream 机 制 的 设计 和 实现 ， 以 此 帮助 读者 全 面 了 解 如 何 使 用 upstream 
访问 上 游 服 务 器 。upstream 机 制 是 事件 驱动 框架 与 HTTP 框 染 的 综合 ， 它 
既 属于 HTTP 框 以 的 一 部 分 ， 又 可 以 处 理 所 有 基于 TCP 的 应 用 层 协议 

(不 限于 HITP) 。 写 不 仅 没有 任何 阻塞 地 实现 了 Nginx 与 上 游 服务 器 的 
交互 ， 同 时 又 很 好 地 解决 了 一 个 请 求 、 多 个 TCP 连 接 、 多 个 读 / 写 事件 间 
的 复杂 关系 。 为 了 帮助 Nginx 实 现 反 辐 代 理 功 能 ，upstream 机 制 除了 提供 
基本 的 与 上 游 交 互 的 功能 之 外 ， 还 实现 了 转发 上 游 应 用 层 协议 的 啊 应 包 
体 到 下 游客 户 站 的 功能 (与 下 游 之 间 当 然 还 是 使 用 HTTP〉。 在 这 些 过 
程 中 ，upstream 机 制 使 用 内 存 时 极其 "节省 ”， 特 别 是 在 转发 啊 应 包 体 

时 ， 它 从 不 会 把 一 份 上 游 的 协议 包 复 制 多 份 。 考 虑 到 上 下 游 间 网 速 的 不 
对 称 ，upstream 机 制 还 提供 了 以 大 内 存 和 磁盘 文件 来 缓存 上 游 啊 应 的 功 








全 已 
月 上。 


因此 ， 拥 有 高 性 能 、 高 效率 以 及 高 度 灵 活性 的 upstream 机 制 值得 我 
们 花费 精力 去 了 解 它 的 设计 、 实 现 ， 这 样 才 能 更 好 地 使 用 它 。 同 时 ， 通 
过 学 习 它 的 设计 思想 ， 也 可 以 深入 了 解 配合 应 用 层 业务 基 于 第 9 章 的 事 
件 框架 开发 Nginx 模 块 的 方法 。 











由 于 upstream 机 制 较为 复杂 ， 同 时 在 第 11 章 “ HTTP 框架” 中 我 们 已 经 


非 第 熟悉 如 何 使 用 事件 驱动 架构 了 ， 所 以 本 章 将 不 会 纠结 于 事件 驱动 淋 
构 的 细节 、 分 支 ， 而 是 专注 于 upstream 机 制 的 主要 流程 。 也 就 是 说 ， 本 
章 将 会 略 过 处 理 upstream 的 过 程 中 超时 、 连 接 关 闭 、 失 败 后 重新 执行 等 
非 核心 事件 ， 仅 聚焦 于 正常 的 处 理 过 程 ( 在 由 源 代 码 对 应 的 流程 图 中 ， 
就 是 会 把 许多 执行 失败 的 分 文 略 过 ， 对 于 这 些 错误 分 支 的 执行 情况 ， 读 
者 可 以 通过 阅读 ngx_http_upstream 源 代码 来 了 解 ) 。 虽 然 upstream 机 制 
也 包含 了 部 分 文件 缓存 功能 的 代码 ， 但 限于 篇 幅 ， 本 章 将 不 介绍 文件 组 
存 ， 这 部 分 内 容 也 会 直接 略 过 。 经 过 这 样 处 理 ， 读 者 就 可 以 清晰 、 直 观 
地 看 到 upstream 到 底 是 如 何 工作 的 了 ， 如 果 还 需要 了 解 细节 ， 那 么 可 以 
由 主要 流程 附近 的 相关 代码 查询 到 各 种 分 支 的 处 理 方式 。 











Nginx 访 问 上 游 服务 器 的 流程 大 致 可 以 分 为 以 下 6 个 阶段 :局 动 
upstream 机 制 、 连 接 上 游 服务 占 、 向 上 游 服 务 器 发 送 请 求 、 接 收 上 游 服 
务 需 的 啊 应 包头 、 处 理 接 收 到 的 啊 应 包 体 、 结 束 请 求 。 本 章 衣 先 在 12.1 
节 系 统 地 讨论 upstream 机 制 的 设计 目的 ， 以 及 为 了 实现 这 些 目的 需要 用 
到 的 数据 结构 ， 之 后 会 按照 顺序 介绍 上 述 6 个 阶段 。 





12.1 upstream 机 制 概述 


本 节 将 说 明 upstream 机 制 的 设计 目的 ， 包 括 它 能 够 解决 哪 几 类 问 
题 。 接 下 来 就 会 介绍 一 个 关键 结构 体 ngx_http_upstream ft 以 及 它 的 conf 
成 员 (ngx_http_upstream_conf _t 结 构 体 ) ， 事 实 上 这 两 个 结构 体 中 的 各 
个 成 员 意义 有 些 混 消 不 清 ， 有 些 仅 用 于 upstream 框 架 使 用 ， 有 些 却 是 布 
望 使 用 upstream 的 HITP 模 块 来 设置 的 ， 这 也 是 C 语 言 编程 的 浆 端 。 因 
此 ， 如 果 和 希望 直接 编写 使 用 upstream 机 制 的 复杂 模块 ， 可 以 采取 顺序 阅 
读 的 方式 ， 如 果 和 希望 更 多 地 了 解 upstream 的 工作 流程 ， 则 不 妨 先 跳 过 对 
这 两 个 结构 体 的 详细 说 明 ， 继 续 癌 下 了 解 upstream 流 程 ， 在 流程 的 每 个 
阶段 中 都 会 使 用 到 这 两 个 结构 体 中 的 成 员 ， 到 时 可 以 再 返回 查询 每 个 成 
员 的 意义 ， 这 样 会 更 有 效率 。 




















12.1.1 设计 目的 


那么 ， 到 底 什 么 是 upstream 机 制 ? 它 的 设计 目的 有 哪些 ? 先 来 看 看 
图 12-1。 


(1) 上 游 和 下 游 


图 12-1 中 出 现 了 上 游 和 下 游 的 概念 ， 这 是 从 Nginx 视 角 上 得 出 的 名 
词 ， 怎 么 理解 呢 ? 我 们 不 妨 把 它 看 成 一 条 产业 链 ，Nginx 是 其 中 的 一 





环 ， 离 消费 者 近 的 环节 属于 下 游 ， 离 消费 者 远 的 环节 属于 上 游 。Nginx 
的 客户 端 可 以 是 一 个 浏览 器 ， 或 者 是 一 个 应 用 程序 ， 又 或 者 是 一 个 服务 
器 ， 对 于 Nginx 来 说 ， 它 们 都 属于 “下 游 *”，Nginx 为 了 实现 “下 游 " 所 需要 
的 功能 ， 很 多 时 候 是 从 * 上 游 ? 的 服务 器 获取 一 些 原材料 的 《如 数据 库 中 
的 用 户 信 息 等 ) 。 图 12-1 中 的 两 个 英文 单词 ，upstream 表 示 上 游 ， 而 
downstream 表 示 下 游 。 因 此 ， 所 谓 的 upstream 机 制 就 是 用 来 使 HTTP 模块 
在 处 理 客户 端 请 求 时 可 以 访问 “上 游 ? 的 后 端 服务 器 。 





客户 问 ( Nginx 的 下 游 ) 





[HTTP 请 求 ] | 基于 HTTP 的 downstream 啊 应 /|] 





[ 基于 TCP 的 请 求 | [基于 TCP 的 upstream 啊 应 ] 


后 病 服 务 硕 ( Nginx 的 上 游 ) 





图 12-1 upstteam 机 制 的 场景 示意 图 
(2) 上 游 服 务 器 提供 的 协议 


Nginx 不 仅仅 可 以 用 做 Web 服 务 器 。upstream 机 制 其 实 是 由 


ngx_http_upstream_module 模 块 实现 的 ， 它 是 一 个 HTTP 模 块 ， 使 用 
upstream 机 制 时 客户 端的 请 求 必 须 基 于 HITP。 


既然 upstream 是 用 于 访问 “上 游 ? 服 务 器 的 ， 那 么 ，Nginx 需 要 访问 什 
么 类 型 的 * 上 游 ? 服 务 器 呢 ? 是 Apache、Tomcat 这 样 的 web 服务 器 ， 还 是 
memcached、cassandra 这 样 的 Key-Value 存 储 系统 ， 又 或 是 mongoDB、 
MySQL 这 样 的 数据 库 ? 这 就 涉及 upstream 机 制 的 范围 了 。 其 实 非常 明 
显 ， 回 顾 一 下 第 9 章 中 系统 介绍 过 的 主要 用 于 处 理 TCP 的 事件 驱动 架 
构 ， 基 于 事件 驱动 架构 的 upstream 机 制 所 要 访问 的 就 是 所 有 支持 TCP 的 
上 游 服务 器 。 因 此 ， 既 有 ngx_http_proxy_module 模 块 基于 upstream 机 制 
实现 了 HTTP 的 反 回 代理 功能 ， 也 有 类 似 ngx_http_memcached_module 的 
模块 基于 upstream 机 制 使 得 请 求 可 以 访问 memcached 服 务 器 。 





(3) 每 个 客户 端 请 求实 际 上 可 以 同 多 个 上 游 服务 器 发 起 请 求 


在 图 12-1 中 ， 似 乎 一 个 客户 端 请 求 只 能 访问 一 个 上 游 服务 器 ， 事 实 
上 并 不 是 这 样 ， 否 则 Nginx 的 功能 就 太 弱 了 。 对 于 每 个 
ngx_http_request_t 请 求 来 说 ， 只 能 访问 一 个 上 游 服 务 器 ， 但 对 于 一 个 客 
户 问 请 求 来 说 ， 可 以 派生 出 许多 子 请 求 ， 任 何 一 个 子 请 求 都 可 以 访问 一 
个 上 游 服务 器 ， 这 些 子 请 求 的 结果 组 合 起 来 就 可 以 使 来 自 客 户 端的 请 求 
处 理 复杂 的 业务 。 








可 为 什么 每 个 ngx_http_request_t 请 求 只 能 访问 一 个 上 游 服 务 器 ? 这 


征 由 于 upstream 机 制 还 有 更 复杂 的 目的 。 以 反问 代理 功能 为 例 ， 
upstream 机 制 需 要 把 上 游 服务 器 的 啊 应 全 部 转发 给 客户 端 ， 那 么 如 宁 啊 
应 的 长 度 特别 大 怎么 办 ? 例如 ， 用 户 下 载 一 个 5GB 的 视频 文件 ， 
upstream 机 制 肯定 不 能 够 在 Nginx 接 收 了 完整 的 啊 应 后 ， 再 把 它 转发 给 客 
户 端 ， 这 样 效率 太 差 了 。 因 此 ，upstream 机 制 不 只 提供 了 直接 处 理 上 游 
服务 占 啊 应 的 功能 ， 还 具有 将 来 自 上 游 服务 费 的 啊 应 即时 转发 给 下 游客 
户 端的 功能 。 因 为 有 了 这 个 独特 的 需求 ， 每 个 ngx_http_request_t 结 构 体 
只 能 用 来 访问 一 个 上 游 服务 器 ， 大 大 简化 了 设计 。 








(4) 反问 代理 与 转发 上 游 服 务 絮 的 啊 应 





转发 啊 应 时 同样 有 两 个 需要 解决 的 问题 。 


1) 下 游 协 议 是 HITP， 而 上 游 协议 可 以 是 基于 TCP 的 任何 协议 ， 这 
需要 有 一 个 适 配 的 过 程 。 所 以 ，upstream 机 制 会 将 上 游 的 响应 划分 为 包 
头 、 包 体 两 部 分 ， 包 头 部 分 必须 由 HTTP 模 块 实现 的 process_header 方 法 
解析 、 处 理 ， 包 体 则 由 upstream 不 做 修改 地 进行 转发 。 


2) 上 、 下 洲 的 网 速 可 能 差别 非常 大 ， 通 币 在 产品 环境 中 ，Nginx 与 
上 游 服务 器 之 间 是 内 网 ， 网 速 会 很 快 ， 而 Nginx 与 下 游 的 客户 问 之 间 则 
征 公 网 ， 网 速 可 能 非常 慢 。 对 于 这 种 情况 ， 将 会 有 以 下 两 种 解决 方案 : 











. 当 上 、 下 游 网 速 差 距 不 大 ， 或 者 下 游 速度 更 快 时 ， 出 于 能 够 并 发 
更 多 请 求 的 考虑 ， 必 然 希 望 内 存 可 以 使 用 得 少 一 些 ， 这 时 将 会 开辟 一 块 


定 大 小 的 内 存 (由 ngx_http_upstteam_conf t 中 的 buffetr_size 指 定 大 

小 ) ， 既 用 它 来 接收 上 游 的 响应 ， 也 用 它 来 把 保存 的 响应 内 容 转发 给 下 
游 。 这 样 做 也 是 有 缺点 的 ， 当 下 游 速度 过 慢 而 导致 这 块 充当 缓冲 区 的 内 
存 写 满 时 ， 将 无 法 再 接收 上 游 的 响应 ， 必 须 等 待 缓 冲 区 中 的 内 容 全 部 发 
送 给 下 游 后 才能 继续 接收 。 


" 当 上 游 网 速 远 快 于 下 游 网 速 时 ， 就 必须 要 开辟 足够 的 内 存 缓冲 区 
米 缓 存 上 游 响应 (ngx_http_upstream_conf_t 中 的 bufs 指 定 了 每 块 内 存 组 
冲 区 的 大 小 ， 以 及 最 多 可 以 有 多 少 块 内 存 缓冲 区 ) ， 当 达到 内 存 使 用 上 
限时 还 会 把 上 游 响 应 缓存 到 磁 一 文件 中 《当然 ， 磁 盘 文 件 也 是 有 大 小 限 
制 的 ，ngx_http_upstream_conf t 中 的 max_temp_file size 指定 了 临时 缓存 
文件 的 最 大 长 度 ) ， 虽 然 内 存 和 磁盘 的 缓冲 都 满 后 ， 仍 然 会 发 生 暂时 无 
法 接收 上 游 响应 的 场景 ， 但 这 种 概率 就 小 得 多 了 ， 特 别 是 临时 文件 的 上 
限 设置 得 较 大 时 。 


转发 啊 应 时 一 个 比较 难以 解决 的 问题 是 Nginx 对 内 存 使 用 得 太 “ 市 
省 ”， 即 从 来 不 会 把 接收 到 的 上 游 啊 应 缓冲 区 复制 为 两 份 。 这 就 带 来 了 
一 个 问题 ， 当 同一 块 缓冲 区 既 用 于 接收 上 游 啊 应 ， 又 用 于 同 下 游 发 送 啊 
应 ， 同 时 可 能 还 在 写 入 临时 文件 ， 那 么 ， 这 块 缓冲 区 何 时 可 以 释放 ， 以 
便 接收 新 的 缓冲 区 呢 ? 对 于 这 个 问题 ，Nginx 是 采用 多 个 ngx_buf_t 结 构 
体 指向 同一 块 内 存 的 做 法 来 解决 的 ， 并 且 这 些 ngx_buf 1t 绥 冲 区 的 shadow 
域 会 互相 引用 ， 以 确保 真实 的 缓冲 区 真 的 不 再 使 用 时 才 会 回收 、 复 用 。 








12.1.2 ngx_http_upstream_t 数 据 结构 的 意义 


使 用 upstream 机 制 时 必须 构造 ngx_http_upstream_t 结 构 体 ， 下 面 详 述 
其 中 每 个 成 员 的 意义 。 








typedef struct ngx_http_upstream s ngx_http_upstream t; 
struct ngx_http_upstream s { 
// 处 理 读 事件 的 回调 方法 ， 每 一 个 阶段 都 有 不 同 的 


read_event_hand1ler 
ngx_http_upstream handler_pt read_ event_handler; 
// 处 理 写 事件 的 回调 方法 ， 每 一 个 阶段 都 有 不 同 的 


write_event_handler 
ngx_http_upstream handler_pt write event_handler; 
/* 表 示 主 动向 上 游 服务 器 发 起 的 连接 。 关 于 


ngx_peer_connection_t 结 构 体 ， 可 参见 


9.3.2 节 


*/ 
ngx_peer_connection_t peer; 
// 当 向 下 游客 户 端 转 发 响应 时 


ngx_http_request 七 结构 体 中 的 


subrequest_in_memory 标 志 位 为 


0) ， 如 果 打 开 了 缓存 且 认为 上 游 网 速 更 快 〈 


conf 配 置 中 的 


buffering 标 志 位 为 


1) ， 这 时 会 使 用 


pipe 成 员 来 转发 响应 。 在 使 用 这 种 方式 转发 响应 时 ， 必 须 由 


HTTP 模 块 在 使 用 


Upstream 机 制 前 构造 


pipe 结 构 体 ， 否 则 会 出 现 严 重 的 





coredump 错 误 。 详 见 


12.8.1 节 


#7 
ngx_event_pipe_t *pipe; 
// 定义 了 向 下 游 发 送 响 应 的 方式 


ngx_output_chain_ctx_t output; 
ngx_chain writer_ctx_t writer,; 
// 使 用 








Upstream 机 制 时 的 各 种 配置 ， 详 见 


12.1.3 节 


ngx_http_upstream conf_t *conf; 
A/*HTTP 模 块 在 实现 


process_header 方 法 时 ， 如 果 希 望 


Upstream 直 接 转 发 响应 ， 就 需要 把 解析 出 的 响应 头 部 适 配 为 


HTTP 的 响应 头 部 ， 同 时 需要 把 包头 中 的 信息 设置 到 


headers_in 结 构 体 中 ， 这 样 ， 在 图 


12-5 的 第 
8 步 中 ， 会 把 


headers_in 中 设置 的 头 部 添加 到 要 发 送 到 下 游客 户 端的 响应 头 部 


headers_out 中 


*/ 


ngx_http_upstream headers_in_t headers_in; 
// 用 于 解析 主机 域名 ， 本 章 不 作 介绍 


ngx_http_upstream resolved t *resolved; 
/* 接 收 上 游 服务 器 响应 包头 的 缓冲 区 ， 在 不 需要 把 响应 直接 转发 给 客户 端 ， 或 者 


buffering 标 志 位 为 


9 的 情况 下 转发 包 体 时 ， 接 收 包 体 的 缓冲 区 仍然 使 用 


buffer。 注 意 ， 如 果 没 有 自 定义 


input_filter 方 法 处 理 包 体 ， 将 会 使 用 


buffer 存 储 全 部 的 包 体 ， 这 时 


buffer 必 须 足 够 大 ! 它 的 大 小 由 


ngx_http_upstream_conf_t 配 置 结构 体 中 的 


buffer_size 成 员 决 定 


7 
ngx_buf_t buffer; 
// 表示 来 自 上 游 服 务 器 的 响应 包 体 的 长 度 


size _t length 
/* Out_bufSs 在 两 种 场景 下 有 不 同 的 意义 : 四 当 不 需要 转发 包 体 ， 且 使 用 默认 的 


input_filter 方 法 (也 就 是 


ngx_http_upstream_non_buffered_filter 方 法 ) 处 理 包 体 时 ， 


Out_bufs 将 会 指向 响应 包 体 ， 事 实 上 ， 





out_bufs 链 表 中 会 产生 多 个 


ngx_buf_t 缓 冲 区 ， 每 个 缓冲 区 都 指向 


buffer 缓 存 中 的 一 部 分 ， 而 这 里 的 一 部 分 就 是 每 次 调用 


recv 方 法 接收 到 的 一 段 


TCP 流 。 回 当 需 要 转发 响应 包 体 到 下 游 时 人 


buffering 标 志 位 为 


上 ， 即 以 下 游 网 速 优先 ， 参 见 


12.7 节 ) ， 这 个 链表 指向 上 一 次 向 下 游 转发 响应 到 现在 这 段 时 间 内 接收 自 上 游 的 缓存 响应 





*/ 

ngx_chain t *out_bufs ; 

/* 当 需要 转发 响应 包 体 到 下 游 时 ( 
buffering 标 志 位 为 


9@， 即 以 下 游 网 速 优先 ， 参 见 


12.7 节 ) ， 它 表示 上 一 次 向 下 游 转发 响应 时 没有 发 送 完 的 内 容 


4 
ngx_chain_t *busy_bufs,; 
/这 个 链表 将 用 于 回收 


Out_bufs 中 已 经 发 送 给 下 游 的 


ngx_buf t 结 构 体 ， 这 同样 应 用 在 


buffering 标 志 位 为 


9 即 以 下 游 网 速 优 先 的 场景 


* 

/ 
ngx_chain_t *free_bufs,; 
/* 处 理 包 体 前 的 初始 化 方法 ， 其 中 


data 参 数 用 于 传递 用 户 数 据 结 构 ， 它 实际 上 就 是 下 面 的 


input_filter_ctx 指 针 


*/ 
ngx_int_t (*input_filter_init)(void *data); 
/* 处 理 包 体 的 方法 ， 其 中 


data 参 数 用 于 传递 用 户 数据 结构 ， 它 实际 上 就 是 下 面 的 


input_filter_ctx 指 针 ， 而 


bytes 表 示 本 次 接收 到 的 包 体 长 度 。 返 回 


NGX_ERROR 时 表示 处 理 包 体 错 误 ， 请 求 需要 结束 ， 否 则 都 将 继续 


Upstream 流 程 


*/ 
ngx_int_t (*input_filter)(void *data, ssize _t bytes); 
/* 用 于 传递 


HTTP 模 块 自 定义 的 数据 结构 ， 在 


input_filter_init 和 


input_filter 方 法 被 回调 时 会 作为 参数 传递 过 去 


*/ 
void *input_filter_ctx; 
// HTTP 模 块 实现 的 


create_request 方 法 用 于 构造 发 往 上 游 服 务 器 的 请 求 


ngx_int_t (*create request)(ngx_http_request t *r); 
/* 与 上 游 服务 器 的 通信 失败 后 ， 如 果 按 照 重 试 规则 还 需要 再 次 向 上 游 服务 器 发 起 连接 ， 则 会 调用 


reinit_request 方 法 


4 
ngx_int_t (*reinit request)(ngx_http_request t *r); 
/* 解 析 上 游 服务 器 返回 响应 的 包头 ， 返 回 


NGX_AGAIN 表 示 包 头 还 没有 接收 完整 ， 返 回 


NGX_HTTP_UPSTREAM_INVALID_HEADER 表 示 包 头 不 合法 ， 返 回 


NGX_ERROR 表 示 出 现 错误 ， 返 回 


NGX_OK 表 示 解 析 到 完整 的 包头 


< 
ngx_int_t (*process header)(ngx_http_request t *r); 
// 当前 版 本 下 


abort_request 回 调 方 法 没有 任意 意义 ， 在 


upstream 的 所 有 流程 中 都 不 会 调用 


x 
void (*abort_request)(ngx_http_request t *r); 
// 请 求 结束 时 会 调用 ， 参 见 


12.9.1 节 


void (*finalize request)(ngx_http_request _t *r, 
ngx_int_t rc); 
/* 在 上 游 返 回 的 响应 出 现 


Location 或 者 


Refresh 头 部 表示 重 定向 时 ， 会 通过 


ngx_http_upstream_process_headers 方 法 (参见 图 


12-5 中 的 第 


8 步 ) 调用 到 可 由 


HTTP 模 块 实现 的 


rewrite_redirect 方 法 


*/ 
ngx_int_t (*rewrite redirect)(ngx_http_request _t *r, 
ngx_table elt t *h, size _t prefix); 
// 暂 无 意义 


ngx_msec_t timeout ; 
// 用 于 表示 上 游 响 应 的 错误 码 、 包 体 长 度 等 信息 


ngx_http_upstream state t *state,; 


// 不 使 用 文件 缓存 时 没有 意义 


ngx_str_t method ; 
// Schema 和 


uri 成员 仅 在 记录 日 志 时 会 用 到 ， 除 此 以 外 没有 意义 


ngx_str_t Schema 
ngx_str_t uri,; 
/* 目 前 它 仅 用 于 表示 是 否 需要 清理 资源 ， 相 当 于 一 个 标志 位 ， 实 际 不 会 调用 到 它 所 指向 的 方法 


*/ 
ngx_http_cleanup_pt *cleanup; 
// 是 否 指定 文件 缓存 路 径 的 标志 位 ， 本 章 不 讨论 文件 缓存 ， 略 过 


unsigned store:1; 
// 是 否 启 用 文件 缓存 ， 本 章 仅 讨论 


cacheable 标 志 位 为 


9 的 场景 


unsigned cacheable:1; 
// 暂 无 意义 


unsigned accel:1; 
// 是 否 基 于 


SSL 协 议 访 问 上 游 服务 器 


unsigned ssl:1; 
/* 向 下 游 转 发 上 游 的 响应 包 体 时 ， 是 否 开局 更 大 的 内 存 及 临时 磁盘 文件 用 于 缓存 来 不 及 发 送 到 下 游 的 响应 包 f 


*/ 
unsigned buffering:1; 
/*request_bufs 以 链表 的 方式 把 


ngXx_buf 七 缓 冲 区 链接 起 来 ， 它 表示 所 有 需要 发 送 到 上 游 服务 器 的 请 求 内 容 。 所 以 ， 


HTTP 模 块 实现 的 


create_request 回 调 方法 就 在 于 构造 


request_bufs 链 表 


ngx_chain_ t *request_ bufs; 
/*request_sent 表 示 是否 已 经 向 上 游 服 务 器 发 送 了 请 求 ， 当 


request_sent 为 





upstream 机 制 已 经 向 上 游 服务 器 发 送 了 全 部 或 者 部 分 的 请 求 。 事 实 上 ， 这 个 标志 位 更 多 的 是 为 了 使 用 


ngx_output_chain 方 法 发 送 请 求 ， 因 为 该 方法 发 送 请 求 时 会 自动 把 未 发 送 完 的 





request_bufs 链 表 记 录 下 来 ， 为 了 防止 反复 发 送 重复 请 求 ， 必 须 有 


request_sent 标 志 位 记录 是 否 调 用 过 


ngx_output_chain 方 法 


< 
unsigned request_sent:1; 
/* 将 上 游 服务 器 的 响应 划分 为 包头 和 包 尾 ， 如 果 把 响应 直接 转发 给 客户 端 ， 


header_sent 标 志 位 表示 包头 是 否 发 送 ， 


header_sent 为 


1 时 表示 已 经 把 包头 转发 给 客户 端 了 。 如 果 不 转发 响应 到 客户 端 ， 则 


header_sent 没 有 意义 


*/ 
unsigned header_sent:1; 


}; 





到 目前 为 止 ，ngx_http_upstream_t 结 构 体 中 有 些 成 员 仍 然 没 有 使 用 到 ， 还 有 更 多 的 成 员 圭 





12.1.3 ngx_http_upstream_conf t 配 置 结构 体 


ngx_http_upstream_t 结 构 体 中 的 conf 成 员 是 非常 关键 的 ， 它 指定 了 upstream 的 运行 方式 。 





typedef struct { 


A 
ngx_http_upstream t 结 构 体 中 没有 实现 
resolved 成 . 员 时 ， 
upstream 这 个 结构 体 才 会 生效 ， 它 会 定义 上 游 服务 器 的 配置 


4 
ngx_http_upstream srv_conf_t *upstream; 


/* 建 立 





TcP 连 接 的 超时 时 间 ， 实 际 上 就 是 写 事件 添加 到 定时 器 中 时 设置 的 超时 时 间 ， 参 见 图 


12-3 中 的 第 
8 步 
ef 


ngx_msec_t connect_ timeout; 


/* 发 送 请 求 的 超时 时 间 。 通 常 就 是 写 事件 添加 到 定时 器 中 设置 的 超时 时 间 ， 参 见 图 


12-4 中 的 第 
3 步 
Wh 


ngx_msec_t send_ timeout; 


/* 接 收 响应 的 超时 时 间 。 通 常 就 是 读 事件 添加 到 定时 器 中 设置 的 超时 时 间 ， 参 见 图 


12-4 中 的 第 
5 步 
六 


ngx_msec_t read timeout 
// 目前 无 意义 


ngx_msec_t timeout; 
// TCP 的 


S0_SNOLOWAT 选 项 ， 表 示 发 送 缓冲 区 的 下 限 


size_t send_lowat; 


图 定义 了 接收 头 部 的 缓冲 区 分 配 的 内 存 大 小 【 
ngx_http_upstream_t 中 的 
buffer 缓 冲 区 ) ， 当 不 转发 响应 给 下 游 或 者 在 
buffering 标 志 位 为 


9 的 情况 下 转发 响应 时 ， 它 同样 表示 接收 包 体 的 缓冲 区 大 小 


size_t buffer_size; 
A/* 仅 当 


buffering 标 志 位 为 

1， 并 且 向 下 游 转 发 响应 时 生效 。 它 会 设置 到 
ngx_event_pipe_t 结 构 体 的 

busy_size 成 员 中 ， 具 体 含义 参见 

12.8.1 节 


Size_t busy_buffers_size' 


/* 在 
buffering 标 志 位 为 
1 时 ， 如 果 上 游 速度 快 于 下 游 速 度 ， 将 有 可 能 把 来 自 上 游 的 响应 存储 到 临时 文件 中 ， 而 
max_temp_file_size 指 定 了 临时 文件 的 最 大 长 度 。 实 际 上 ， 它 将 限制 


ngx_event_pipe_t 结 构 体 中 的 


temp_file*/ 
size _t max_ temp_file size; 


// 表示 将 缓冲 区 中 的 响应 写 入 临时 文件 时 一 次 写 入 字符 流 的 最 大 长 度 


Size_t temp_file write size; 


// 以 下 





3 个 成 员 目 前 都 没有 任何 意义 


size_t busy_buffers_ size conf; 
Size_t max_temp_file size conf; 
Size_t temp_file write size conf; 


// 以 缓存 响应 的 方式 转发 上 游 服务 器 的 包 体 时 所 使 用 的 内 存 大 小 











ngx_bufs_t bufs; 


/* 针 对 
ngx_http_upstream_t 结构 体 中 保存 解析 完 的 包头 的 


headers_in 成 员 ， 


ignore_headers 可 以 按照 二 进 制 位 使 得 

upstream 在 转发 包头 时 跳 过 对 某 些 头 部 的 处 理 。 作 为 
32 位 整 型 ， 理 论 上 

ignore_headers 最 多 可 以 表示 


32 个 需要 跳 过 不 子 处 理 的 头 部 ， 然而 目 前 


upstream 机 制 仅 提 供 
8 个 位 用 于 忽略 
8 个 


HTTP 头 部 的 处 理 ， 包 括 : 


#define NGX_HTTP_UPSTREAM_IGN_XA_REDIRECT 0x00000002 














#define NGX_HTTP_UPSTREAM_IGN_XA_EXPIRES 90x00000004 
#define NGX_HTTP_UPSTREAM_IGN_EXPIRES 90x00000008 
#define NGX_HTTP_UPSTREAM_IGN_CACHE_CONTROL Qx00000010 
#define NGX_HTTP_UPSTREAM_IGN_SET_ COOKIE 90x00000020 





#define NGX_HTTP_UPSTREAM_IGN_XA_LIMIT_RATE Qx00000040 

#define NGX_HTTP_UPSTREAM_IGN_XA_BUFFERING 0x00000080 

#define NGX_HTTP_UPSTREAM_IGN_XA_CHARSET Qx00000100*/ 
ngx_uint_t ignore_headers; 


/* 以 二 进 制 位 来 表示 一 些 错误 码 ， 如 果 处 理 上 游 响应 时 发 现 这 些 错误 码 ， 那 么 在 没有 将 响应 转发 给 下 游客 户 











12.9 节 中 介绍 的 


ngx_http_upstream_next 方法 


*/ 
ngx_uint_t next_upstream; 


/* 在 
buffering 标 志 位 为 
1 的 情况 下 转发 响应 时 ， 将 有 可 能 把 响应 存放 到 临时 文件 中 。 在 
ngx_http_upstream_t 中 的 
store 标 志 位 为 
1 时 ， 


store_access 表 示 所 创建 的 目录 、 文 件 的 权限 


SA 
ngx_uint_t Store_access 


/* 决 定 转发 响应 方式 的 标志 位 ， 
buffering 为 
1 时 表示 打开 缓存 ， 这 时 认为 上 游 的 网 速 快 于 下 游 的 网 速 ， 会 尽量 地 在 内 存 或 者 磁盘 中 缓存 来 自 上 游 的 响应 ; 如 


buffering 为 


9， 仅 会 开辟 一 块 固定 大 小 的 内 存 块 作为 缓存 来 转发 响应 


* 

/ 
ngx_flag_t buffering; 
// 蜀 无 意义 


ngx_flag_t pass_request_headers; 


// 暂 无 意义 





ngx_flag_t pass_request_body; 
/表示 标志 位 。 当 它 为 





1 时 ， 表 示 与 上 游 服务 器 交互 时 将 不 检查 


Nginx 与 下 游客 户 端 间 的 连接 是 否 断 开 。 也 就 是 说 ， 即 使 下 游客 户 端 主动 关闭 了 连接 ， 也 不 会 中 断 与 上 游 服务 器 


5 
ngx_flag_t ignore client abort; 


/* 当 解析 上 游 响 应 的 包头 时 ， 如 果 解 析 后 设置 到 





headers_in 结 构 体 中 的 

status_n 错 误 码 大 于 

499， 则 会 试图 把 它 与 

error_page 中 指定 的 错误 码 相 匹配 ， 如 果 匹 配 上 ， 则 发 送 
error_page 中 指定 的 响应 ， 否 则 继续 返回 上 游 服务 器 的 错误 码 。 详 见 
ngx_http_upstream_intercept_errors 方 法 

*/ 


ngx_flag_t intercept_ errors; 
/*buffering 标 志 位 为 


1 的 情况 下 转发 响应 时 才 有 意义 。 这 时 ， 如 果 
cyclic_temp_file 为 

1， 则 会 试图 复 用 临时 文件 中 己 经 使 用 过 的 空间 。 不 建议 将 
cyclic_temp_file 设 为 


1 
ngx_flag_t cyclic temp_file; 


// 在 





buffering 标 志 位 为 
1 的 情况 下 转发 响应 时 ， 存 放 临 时 文件 的 路 径 


ngx_path_t *temp_path 
/* 不 转发 的 头 部 。 实 际 上 是 通过 


ngx_http_upstream_hide_headers_hash 方 法 ， 根 据 





hide_headers 和 
pass_headers 动 态 数 组 构造 出 的 需要 隐藏 的 


HTTP 头 部 散 列 表 


/ 
ngx_hash_t hide_headers_hash; 


/* 当 转发 上 游 响应 头 部 ( 





ngx_http_upstream_t 中 
headers_in 结 构 体 中 的 头 部 ) 给 下 游客 户 端 时 ， 如 果 不 希 望 某 些 头 部 转发 给 下 游 ， 就 设置 到 
hide_headers 动 态 数组 中 


*y 
ngx_array_t *hide_ headers; 


/* 当 转发 上 游 响应 头 部 ( 
ngx_http_upstream_t 中 
headers_in 结 构 体 中 的 头 部 ) 给 下 游客 户 端 时 ， 
upstream 机 制 默认 不 会 转发 如 “ 


人 


Date” 、 
Server” 之 类 的 头 部 ， 如 果 确 实 希 望 直接 转发 它们 到 下 游 ， 就 设置 到 
pass_headers 动 态 数 组 中 


*y 
ngx_array_t *pass_headers; 


// 连接 上 游 服务 器 时 使 用 的 本 机 地 址 


ngx_addr_t *local; 


/* 当 
ngx_http_upstream t 中 的 
store 标 志 位 为 
1 时 ， 如 果 需 要 将 上 游 的 响应 存放 到 文件 中 ， 
store_lengths 将 表示 存放 路 径 的 长 度 ， 而 
store_values 表 示 存 放 路 径 
/ 


ngx_array_t *store_lengths 
ngx_array_t *store_values 


/* 到 目前 为 止 ， 
store 标 志 位 的 意义 与 


ngx_http_upstream t 中 的 


store 相 同 ， 仍 只 有 
0 和 


1 被 使 用 到 


6 
signed store:2; 


/* 上 面 的 
intercept_errors 标 志 位 定义 了 
499 以 上 的 错误 码 将 会 与 
error_page 比 较 后 再 行 处 理 ， 实 际 上 这 个 规则 是 可 以 有 一 个 例外 情况 的 ， 如 果 将 
intercept_404 标 志 位 设 为 
1， 当 上 游 返 回 
464 时 会 直接 转发 这 个 错误 码 给 下 游 ， 而 不 会 去 与 
error_page 进 行 比较 
SA 


unsigned intercept_ 404:1; 
/* 当 该 标志 位 为 


1 时 ， 将 会 根据 

ngx_http_upstream_t 中 

headers_in 结 构 体 里 的 
X-Accel-Buffering 头 部 ( 它 的 值 会 是 
yes 和 

no) 来 改变 
buffering 标 志 位 ， 当 其 值 为 

yes 时 ， 

buffering 标 志 位 为 

1s 因 兹 ， 

change_buffering 为 

1 时 将 有 可 能 根据 上 游 服务 器 返回 的 响应 头 部 ,动态 地 决定 是 以 上 游 网 速 优先 还 是 以 下 游 网 速 优先 
x 


unsigned change_ buffering:1; 


// 使 用 


upstream 的 模块 名 称 ， 仅 用 于 记录 日 志 


ngx_str_t module; 
} ngx_http_upstream conf_t; 


ee | 








ngx_http_upstream_conf_t 结 构 体 中 的 配置 都 比较 重要 ， 它 们 会 影响 访问 上 游 服 务 器 的 方式 。 同 时 ， 该 结构 件 





























12.2 ”局 动 upstream 


在 把 请 求 里 ngx_http_request_t 结 构 体 中 的 upstream 成 员 
(ngx_http_upstream _t 类 型 ) 创建 并 设置 好 ， 并 且 正 确 设置 upstream- 
>conf 配 置 结 构 体 Cngx_http_upstream_conf t 类 型 ) 后， 就 可 以 启动 
upstream 机 制 了 。 局 动 方式 非常 简单 ， 调 用 ngx_http_upstream_init 方 法 
即 可 。 





注意 ， 默 认 情 况 下 请 求 的 upstream 成 员 只 是 NULL 空 指针 ， 在 设置 
upstream 之 前 需要 调用 ngx_http_upstream_create 方 法 从 内 存 池 中 创建 
ngx_http_upstream _t 结 构 体 ， 访 方法 的 原型 如 下 。 





ngx_int_t ngx_http_upstream create(ngx_http_request _t *r) 








ngx_http_upstream_create 方 法 只 是 创建 ngx_http_upstream_t 结 构 体 而 
己 ， 其 中 的 成 员 还 需要 各 个 HTTP 模 块 自行 设置 。 启 动 upstream 机 制 | 的 


ngx_http_upstream_init 方 法 定义 如 下 。 





void ngx_http_upstream init(ngx_http_request_t *r) 





ngx_http_upstream_init 方 法 将 会 根据 ngx_http_upstream_conf_t 中 的 
成 员 初 始 化 upstream， 同 时 会 开始 连接 上 游 服 务 器 ， 以 此 展开 整个 


upstream 处 理 流程 。 图 12-2 简 要 描述 了 ngx_http_upstream_init 方 法 所 做 的 
主要 证 作 。 


[检查 下 游 连接 读 事 件 的 timer set 标 志 位 ] 





[ 读 事 件 在 定时 天 中 ] 


1) 将 客户 端 连接 的 读 事件 由 和 
定时 器 中 移 除 


[检查 ignore client _abort 配 置 ] 











[ignore_client_abort 为 1] 
[ignore_client_abort 为 0| 





2 ) 设 置 检查 Nginx 
与 下 游客 户 端 连接 状态 的 方法 





3 ) 调 用 HTTP 模 块 实现 的 
create_request 方法 










4) 将 ngx_http_upstream_cleanup 


方法 添加 到 cleanup 链 表 





5) 调用 ngx_http_upstream_connect 


方法 连接 上 游 服务 天 


图 12-2 ngx_http_upstream_init 方 法 的 流程 图 


下 面 依次 说 明 图 12-2 中 各 个 步骤 的 意义 。 





1) 首先 检查 请 求 对 应 于 客户 端的 连接 ， 这 个 连接 上 的 读 事件 如 果 
在 定时 堪 中 ， 也 就 是 说， 读 事 件 的 timer_set 标 志 位 为 1， 那 么 调用 
ngx_del_timer 方 法 把 这 个 读 事 件 从 定时 融 中 移 除 。 为 什么 要 做 这 件 事 
呢 ? 因为 一 旦 局 动 upstream 机 制 ， 就 不 应 该 对 客户 端的 该 操作 带 有 超时 
时 间 的 处 理 ， 请 求 的 主要 触发 事件 将 以 与 上 游 服务 器 的 连接 为 主 。 








2) 检查 ngx_http_upstream_conf_t 配 置 结构 中 的 ignore_client_abort 标 
志 位 (参见 12.1.3 节 ) ， 如 果 ignore_client_abort 为 1， 则 跳 到 第 3 步 ， 否 
则 (实际 上 ， 还 需要 让 store 标 志 位 为 0、 请 求 ngx_http_request_t 结 构 体 中 
的 post_action 标 志 位 为 0) 束 会 设置 Nginx 与 下 游客 户 端 之 间 TCP 连 接 的 
检查 方法 ， 如 下 所 示 。 





r->read event_handler = ngx_http_upstream rd_check_broken_connection,; 
r->write event_handler = ngx_http_upstream wr_check_broken_connection,; 











实际 上 ， 这 两 个 方法 都 会 通过 
ngx_http_upstream_check_broken_connection 方 法 检查 Nginx 与 下 游 的 连 
接 是 否 正常 ， 如 果 出 现 错误 ， 束 会 立即 终止 连接 。 


3) 调用 请 求 中 ngx_http_upstream_t 结 构 体 里 由 某 个 HTTP 模 块 实现 
的 create_request 方 法 ， 构 造 肥 往 上 游 服 务 器 的 请 求 ( 请 求 中 的 内 容 是 设 
置 到 request_bufs 绥 冲 区 链表 中 的 ) 。 如 果 create_request 方 法 没有 返回 
NGX_OK， 则 upstream 机 制 结束 ， 此 时 会 调用 11.10.6 节 中 介绍 过 的 


ngx_http_finalize_request 方 法 来 结束 请 求 。 


4) 在 11.10.2 节 中 介绍 过 ，ngx_http_cleanup_t 是 用 于 清理 资源 的 结 
构 体 ， 还 说 明了 它 何 时 会 被 执行 。 在 这 一 步 中 ，upstream 机 制 就 用 到 了 
ngx_http_cleanup_t。 首 先 ， 调 用 ngx_http_cleanup_add 方 法 向 这 个 请 求 
main 成 员 指向 的 原始 请 求 中 的 cleanup 链 表 末 尾 添加 一 个 新 成 员 ， 然 后 把 
handler 回 调 方法 设 为 ngx_http_upstream_cleanup， 这 意味 着 当 请 求 结束 








时 ， 一 定 会 调用 ngx_http_upstream_cleanup 方 法 〈 人 参见 12.9.1 节 ) 。 


5) 调用 ngx_http_upstream_connect 方 法 向 上 游 服务 器 发 起 连接 〈 详 


见 12.3 节 ) 。 


@@ 注意 启动 upstream 机 制 时 还 有 许多 分 支流 程 ， 如 缓存 文件 的 
使 用 、 上 游 服务 器 地 址 的 选取 等 ， 图 12-2 概 括 了 最 主要 的 5 个 步 又， 这 样 
方便 读者 了 解 upstream 的 核心 思想 。 其 他 分 支 的 处 理 不 影响 这 5 个 主要 流 
程 ， 如 需 了 解 可 自行 查看 ngx_http_upstream_init 和 


ngx_http_upstream_init_request 方 法 的 源 代 码 。 


12.3 与 上 游 服 务 器 建立 连接 


upstream 机 制 与 上 游 服 务 器 是 通过 TCP 建 立 连接 的 ， 众 所 周知 ， 建 
TCP 连接 需要 三 次 握手 ， 而 三 次 握手 消耗 的 时 间 是 不 可 控 的 。 为 了 保 
证 建立 TCP 连 接 这 个 操作 不 会 阻塞 进程 ，Nginx 使 用 无 阻塞 的 套 接 字 来 
连接 上 游 服 务 器 。 图 12-2 的 第 5 步调 用 的 ngx_http_upstream_connect 方 法 
就 是 用 来 连接 上 游 服务 器 的 ， 由 于 使 用 了 非 阻 塞 的 套 接 字 ， 当 方法 返回 
时 与 上 游 之 间 的 TCP 连 接 未 必 会 成 功 建立 ， 可 能 还 需要 等 待 上 游 服 务 器 
返回 TCP 的 SYN/ACK 包 。 因 此 ，ngx_http_upstream_connect 方 法 主要 负 

员 发 起 建立 连接 这 个 动作 ， 如 果 这 个 方法 没有 立刻 返回 成 功 ， 那 么 需要 
在 epol 中 监控 这 个 套 接 字 ， 当 它 出 现 可 写 事件 时 ， 就 说 明 连 接 已 经 建立 
成 功 了 。 











在 图 12-3 中 可 以 看 到 ， 如 果 连 接 立 刻 成 功 建立 ， 在 第 9 步 就 会 开始 
向 上 游 服 务 器 发 送 请 求 ， 如 果 连 接 没有 马上 建立 成 功 ， 在 第 8 步 就 会 将 
个 连接 的 写 事件 加 入 a 到 epoll 中 ， 等 待 连接 上 的 可 写 事件 被 触发 后 ， 回 
调 ngx_http_upstream_send_request 方 法 发 送 请 求 给 上 游 服 务 器 。 


下 面 详细 说 明 图 12-3 中 每 个 步骤 的 意义 。 


1) 调用 socket 方 法 建立 一 个 TCP 套 接 字 ， 同 时 ， 这 个 套 接 字 需要 设 
置 为 非 阻塞 模式 。 





2) 由 于 Nginx 的 事件 框架 要 求 每 个 连接 都 由 一 个 ngx_connection_t 结 
构 体 来 承载 ， 因 此 这 一 步 将 调用 ngx_get_connection 方 法 ， 由 ngx_cycle_t 
核心 结构 体 中 free_connections 指 向 的 空闲 连接 池 处 获取 到 一 个 
ngx_connection_t 结 构 体 ， 作 为 承载 Nginx 与 上 游 服务 器 间 的 TCP 连 接 。 


3) 第 9 章 我 们 介绍 过 事件 模块 的 ngx_event_actions 接 口 ， 其 中 的 
add_conn 方 法 可 以 将 TCP 套 接 字 以 期 竺 可 读 、 可 写 事件 的 方式 添加 到 事 
件 搜集 器 中 。 对 于 epoll 事 件 模 块 来 说 ，add_conn 方 法 就 是 把 套 接 字 以 期 
待 EPOLLINIEPOLLOUT 事 件 的 方式 加 入 epol 中 ， 这 一 步 即 调用 
add_conn 方 法 把 刚刚 建立 的 套 接 字 汪 加 到 epol 中 ， 表 示 如 果 这 个 套 接 字 
上 出 现 了 预期 的 网 络 事件 ， 则 希望 epoll 能 够 回调 它 的 handler 方 法 。 















套 接 字 


2) 由 生 尖 六 迫 宙 je 


ngx_connection_t 结 构 



















3) 将 连接 对 应 的 套 接 字 添加 到 
epoll 中 来 监控 读 / 写 事件 






4 ) 调 用 connect 
方法 连接 上 游 服务 器 









5) 设 置 连接 读 / 写 事 件 
的 回调 方法 








6 ) 设 置 upstream 机 制 的 
write_event handler 方 法 









7) 设置 upstream 栅 制 的 
read_event handle 访 法 


[检测 第 4 步 connect 的 返回 值 ] 
[连接 建立 成 功 ] 
[等 待 上 游 服 务 器 的 返回 ] 


8) 将 连接 的 写 事 件 
添加 到 定时 带 中 






9) 调用 ngx_http_upstream_send_request 


方法 发 送 请 求 





图 12-3 ngx_http_upstream_connect 方 法 的 流程 图 


4) 调用 connect 方 法 同上 游 服务 器 及 起 TCP 连 接 ， 作 为 非 阻 窟 僚 接 
字 ，connect 方 法 可 能 立刻 返回 连接 建立 成 功 ， 也 可 能 告诉 用 户 继续 等 待 
上 游 服务 怖 的 啊 应 ， 对 connect 连 接 是 否 建立 成 功 的 检查 会 在 第 7 步 之 后 
进行 。 注 意 ， 这 里 并 没有 涉及 connect 返 回 失败 的 情形 ， 读 者 可 以 参考 第 
11 章 中 这 种 系统 调用 失败 后 的 处 理 ， 本 章 不 会 讨论 细节 。 


5) 将 这 个 连接 ngx_connection_t 上 的 读 / 写 事件 的 handler 回 调 方法 都 
设置 为 ngx_http_upstream_handler。 下 文 会 介绍 


ngx_http_upstream_handler 方 法 。 


6) 将 upstream 机 制 的 write_event_handler 方 法 设 为 
ngx_http_upstream_send_request_handler。write_event_handler 和 和 
read_event_handler 的 用 法 参见 下 面 将 要 介绍 的 ngx_http_upstream_handler 
方法 。 这 一 步 又 实际 上 决定 了 同上 游 服 务 占 发 送 请 求 的 方法 是 


ngx_http_upstream_send_request_handler。 


7) 设置 upstream 机 制 的 read_event_handler 方 法 为 
ngX_http_upstream_process_header， 也 就 是 由 


ngx_http_upstream_process_header 方 法 接收 上 游 服务 器 的 啊 应 。 


现在 开始 检查 在 第 4 步 中 调用 connect 方 法 连接 上 游 服 务 器 是 否 成 


功 ， 如 果 已 经 连接 成 功 ， 则 跳 到 第 9 步 执 行 ， 如 果 尚 未 收 到 上 游 服 务 器 
连接 建立 成 功 的 应 答 ， 则 跳 到 第 8 步 执 行 。 


8) 这 一 步 处 理 非 阻塞 的 连接 尚未 成 功 建立 时 的 动作 。 实 际 上 ， 在 
第 3 步 中 ， 套 接 字 已 经 加 入 到 epoll 中 监控 了 ， 因 此 ， 这 一 步 将 调用 
ngx_add_timer 方 法 把 写 事件 谎 加 到 定时 右 中 ， 超 时 时 间 就 是 12.1.3 节 中 
介绍 的 ngx_http_upstream_conf t 结 构 体 中 的 connect_timeout 成 员 ， 这 是 


在 设置 建立 TCP 连 接 的 超时 时 间 。 


9) 如 果 已 经 成 功 建 立 连 接 ， 则 调用 ngx_http_upstream_send_request 
方法 向 上 游 服 务 器 发 送 请 求 。 注 意 ， 在 第 6 步 中 设置 的 发 送 请 求 方法 为 
ngx_http_upstream_send_request_handler， 它 与 


ngx_http_upstream_send_request 方 法 的 不 同 之 处 将 在 12.4 节 中 介绍 。 








以 上 的 第 5、 第 6、 第 7 步 都 与 ngx_http_upstream_handler 方 法 相关 ， 
同时 我 们 又 看 到 了 类 似 ngx_http_request_t 结 构 体 中 write_event_handler、 
read_event_handler 的 同名 方法 。 实 际 上 ，ngx_http_upstream_handler 方 法 
与 图 11-7 展 示 的 ngx_http_request_handler 方 法 也 非常 相似 ， 下 面 看 看 它 
到 底 做 了 些 什么 。 





static void ngx_http_upstream handler(ngx_event_t *ev) 


ngx_connection _t *c; 
ngx_http_request_t *r,; 
ngx_http_upstream t *u; 
/由 事件 的 





data 成 员 取 得 


ngx_connection_t 连 接 。 注 意 ， 这 个 连接 并 不 是 


Nginx 与 客户 端的 连接 ， 而 是 


Nginx 与 上 游 服务 器 间 的 连接 


*/ 
C = ev->data,; 
// 由 连接 的 
data 成 员 取 得 


ngx_http_request 七 结构 体 


r = c->data,; 
/* 由 请 求 的 


Upstream 成 员 取 得 表示 


Upstream 机 制 的 


Ngx_http_upstream tt 结构 体 


*/ 
U = r->upstream; 


/* 注 意 ， 


ngx_http_request_t 结 构 体 中 的 这 个 


connection 连 接 是 客户 端 与 


Nginx 间 的 连接 


Ap 
Cc = r->connection; 
if (ev->write) { 
/* 当 


Nginx 与 上 游 服 务 器 间 





TCP 连 接 的 可 写 事件 被 触发 时 ， 


Upstream 的 


write_event_handler 方 法 会 被 调用 


*/ 
U->write_event_handler(r, u); 
} else { 
/* 当 


Nginx 与 上 游 服务 器 间 


TCP 连 接 的 可 读 事 件 被 触发 时 ， 


Upstream 的 


read_event_handler 方 法 会 被 调用 


2 


Uu->read_ event_handler(r, u); 


/*ngx_http_run_posted_requests 方 法 正 是 第 





11-12 所 说 的 方法 。 注 意 ， 这 个 参数 


C 是 来 自 客户 端的 连接 ， 


post 请 求 的 执行 也 与 图 


11-12 完 全 一 致 


A 


} 


二 一 





ngx_http_run_posted_ requests(c); 


12.4 发 送 请 求 到 上 游 服 务 器 





向 上 游 服务 器 发 送 请 求 是 一 个 阶段 ， 因 为 请 求 的 大 小 是 未 知 的 ， 所 
以 发 送 请 求 的 方法 需要 被 epol 调 度 许多 次 后 才 可 能 发 送 完 请 求 的 全 部 内 
容 。 在 图 12-3 中 的 第 6 步 将 ngx_http_upstream_t 里 的 write_event_handler 成 
员 设 为 ngx_http_upstream_send_request_handler 方 法 ， 也 就 是 说 ， 由 该 方 
法 负责 反复 地 发 送 请 求 ， 可 是 ， 在 图 12-3 的 第 9 步 又 直接 调用 了 
ngx_http_upstream_send_request 方 法 发 送 请 求 ， 那 这 两 种 方法 之 间 有 什 
么 关系 吗 ? 先 来 看 看 前 者 的 实现 ， 它 相对 简单 ， 这 里 直接 列举 了 它 的 主 
要 源 代码 ， 如 下 所 示 。 








static void ngx_http_upstream send_request_ handler(ngx_http_request t *r, 
ngx_http_upstream t *u) 


ngx_connection _t *c; 


// 获取 与 上 游 服务 器 间 表示 连接 的 


ngx_connection_t 结 构 体 


c = u->peer.connection; 
// 写 事件 的 


timedout 标 志 位 为 


1 时 表示 向 上 游 服务 器 发 送 的 请 求 已 经 超时 


if (c->write->timedout) { 
/* 将 超时 错误 传递 给 





ngx_http_upstream_next 方 法 ， 该 方法 将 会 根据 允许 的 错误 重 连 策略 决定 : 重新 发 起 连接 执行 


upstream 请 求 ， 或 者 结 


upstream 请 求 ， 详 见 


12.9.2 节 

*/ 
ngx_http_upstream next(r, u, NGX_HTTP_UPSTREAM_FT_TIMEOUT); 
return; 

} 


/*header_sent 标 志 位 为 


1 时 表明 上 游 服务 器 的 响应 需要 直接 转发 给 客户 端 ， 而 且 此 时 


Nginx 已 经 把 响应 包头 转发 给 客户 端 了 


*/ 
if (u->header_ sent) { 
/* 事 实 上 ， 





header_sent 为 


1 时 一 定 是 已 经 解析 完全 部 的 上 游 响应 包头 ， 并 且 开 始 向 下 游 发 送 


HTTP 的 包头 了 。 到 此 ， 是 不 应 该 继续 向 上 游 发 送 请 求 的 ， 所 以 把 


write_event_handler 设 为 任何 工作 都 没有 做 的 


ngx_http_upstream_dummy_handJer 方 法 


U->write_event_handler = ngx_http_upstream dummy_handler; 
// 将 写 事件 添加 到 





epoll 中 


(void) ngx_handle write event(c->write, 0); 
// 因为 不 存在 继续 发 送 请 求 到 上 游 的 可 能 ， 所 以 直接 返回 








return 


} 
// 调用 


ngx_http_upstream_send_request 方 法 向 上 游 服 务 器 发 送 请 求 


ngx_http_upstream_ send_request(r, u); 





可 见 ，ngx_http_upstream_send_request_handler 方 法 更 多 的 时 候 是 在 
检测 请 求 的 状态 ， 而 实际 负责 发 送 请 求 的 方法 是 
ngX_http_upstream_send_redquest， 图 12-4 列 出 了 


ngx_http_upstream_send_request 方 法 的 主要 执行 步 又 。 
下 面 说 明 以 上 8 个 步骤 的 意义 。 


1) 调用 ngx_output_chain 方 法 向 上 游 服 务 器 发 送 
ngX_http_upstream_t 结 构 体 中 的 redquest_bufs 链 表 ， 这 个 方法 对 于 发 送 组 
冲 区 构成 的 ngx_chain_t 链 表 非 常 有 用 ， 它 会 把 未 发 送 完成 的 链表 绥 冲 区 
保存 下 来 ， 这 样 就 不 用 每 次 调用 时 都 携带 上 request_bufs 链 表 。 人 怎么 理解 
呢 ? 当 第 一 次 调用 ngx_output_chain 方 法 时 ， 需 要 传递 request_bufs 链 表 
构成 的 请 求 ， 如 下 所 示 。 








rc = ngx_output_chain(&u->output, u->request_bufs); 





这 里 的 u 就 是 请 求 对 应 的 ngx_http_request_t 结 构 体 中 的 upstream 成 员 
(ngx_http_upstream_t 类 型 )， 如 果 ngx_output_chain 一 次 无 法 发 送 完 所 
有 的 request_bufs 请 求 内 容 ，ngx_output_chain_ctx_t 类 型 的 u->output 会 把 


未 发 送 完 的 请 求 保 存在 自己 的 成 员 中 ， 同 时 返回 NGX_AGAIN。 当 可 写 





事件 再 次 触发 ， 发 送 请 求 时 吏 不 需要 再 传递 参数 了 ， 例 如 : 





rc = ngx_output_chain(&u->output, NULL); 





为 了 标识 这 一 点 ，ngx_http_upstream_t 结 构 体 中 专门 有 一 个 标志 位 
request_sent 表 示 是 否 已 经 传递 了 request_bufs 绥 冲 区 。 因 此 ， 在 第 一 次 以 
request_bufs 作 为 参数 调用 ngx_output_chain 方 法 后 ，request_sent 会 置 为 





1。 


2) 检测 写 事件 的 timer_set 标 志 位 ，timer_set 为 1 时 表示 写 事件 仍然 
在 定时 器 中 ， 那 么 这 一 步 首先 把 写 事件 由 定时 器 中 取出 ， 再 由 
ngx_output_chain 的 返回 值 决定 是 否 再 次 向 定时 器 中 加 入 写 事 件 ， 那 时 
超时 时 间 也 会 重 置 。 










1 ) 发 送 缓冲 区 中 的 请 求 内 容 
到 上 游 服务 天 





2 ) 若 写 事件 在 定时 器 中 则 移 除 
[检测 第 1 步 中 ngx_output_chain 方 法 返回 值 ] 
Cy [未 发 送 完全 部 请 求 ] 


[已 发 送 完 全 部 请 求 , 准备 接收 响应 ] 





3) 将 写 事件 添加 到 定时 器 中 





5 ) 将 读 事 件 添加 到 定时 器 中 





[检测 读 事 件 的 ready 标 志 位 ] 4 ) 将 写 事 件 添加 到 epoll 中 





全 [ 暂 无 响应 可 读 ] 


[如 果 套 接 字 缓冲 区 中 有 数据 可 读 ] 


7) 设 置 write __event_handler 方 ; 








6) 调用 ngx_http upstream_process_header 





方法 接收 响应 头 部 





8 ) 将 写 事 件 添 加 到 epoll 中 





® 


图 12-4 ngx_http_upstream_send_request 方 法 的 流程 图 


检测 ngx_output_chain 的 返回 值 ， 返 回 NGX_AGAIN 时 表示 还 有 请 求 
未 被 发 送 ， 此 时 跳 到 第 3 步 ， 如 果 人 返回 NGX_OK， 则 表示 已 经 发 送 完 全 


部 请 求 ， 跳 到 第 5 步 执行 。 
3) 调用 ngx_add_timer 方 法 将 写 事 件 添 加 到 定时 器 中 ， 防 止 发 送 请 


求 超时 。 超 时 时 间 就 是 ngx_http_upstream_conf _t 配 置 结构 体 的 


send timeout 成 员 。 


4) 调用 ngx_handle_write_event 方 法 将 写 事 件 添加 到 epoll 中 ， 


ngx_http_upstream_send_request 方 法 结束 。 
5) 如 果 已 经 同上 游 服 务 器 发 送 完 全 部 请 求 ， 这 时 将 准备 开始 处 理 
响应 ， 首 先 把 读 事 件 添加 到 定时 器 中 检查 接收 啊 应 是 否 超 时 ， 超 时 时 间 


就 是 ngx_http_upstream_conf t 配 置 结构 体 的 read_timeout 成 员 。 








检测 读 事件 的 ready 标 志 位 ， 如 果 ready 为 1， 则 表示 已 经 有 响应 可 以 
读 出 ， 这 时 跳 到 第 6 步 执行 ， 如 果 ready 为 0， 则 跳 到 第 7 步 执行 。 


6) 调用 ngx_http_upstream_process_header 方 法 接收 上 游 服务 器 的 响 
应 ， 在 12.5 节 中 会 详细 讨论 该 方法 。 





7) 如 果 暂 无 啊 应 可 读 ， 由 于 此 时 请 求 已 经 全 部 发 送 到 上 游 服务 器 
了 ， 所 以 要 防止 可 写 事件 再 次 触发 而 又 调用 


ngx_http_upstream_send_request 方 法 。 这 时 ， 把 write_event_handler 设 为 





ngx_http_upstream_dummy_handler 方 法 ， 前 文 说 过 ， 该 方法 不 会 做 任何 
事情 。 这 样 即使 与 上 游 间 的 TCP 连 接 上 再 次 有 可 写 事件 时 也 不 会 有 任何 


动作 发 生 ， 它 就 像 第 11 章 我 们 介绍 的 ngx_http_empty_handler 方 法 。 
8) 调用 ngx_handle_write_event 方 法 将 写 事 件 加 入 到 epoll 中 。 


在 发 送 请 求 到 上 游 服 务 器 的 这 个 阶段 中 ， 每 当 TCP 连 接 上 再 次 可 以 
发 送 字符 流 时 ， 虽 然 事 件 框 架 就 会 回调 
ngx_http_upstream_send_request_handler 方 法 处 理 可 写 事件 ， 但 最 终 还 是 
通过 调用 ngx_http_upstream_send_request 方 法 把 请 求 发 送出 去 的 。 





12.5 接收 上 游 服务 喜 的 啊 应 头 部 


当 请 求全 部 发 送 给 上 游 服 务 器 时 ，Nginx 开 始 准备 接收 来 自 上 游 服 
务 器 的 响应 。 在 图 12-3 的 第 7 步 中 设置 了 由 
ngx_http_upstream_process_header 方 法 处 理 上 游 服 务 器 的 啊 应 ， 而 网 12- 
4 的 第 8 步 也 是 通过 调用 该 方法 接收 啊 应 的 ， 本 节 的 内 容 就 在 于 说 明 可 能 
会 被 反复 多 次 调用 的 ngx_http_upstream_process_header 方 法 。 





12.5.1 ”应 用 层 协 议 的 两 段 划 分 方式 


在 12.1.1 节 我 们 已 经 了 解 到 ， 只 要 上 游 服 务 器 提供 的 应 用 层 协议 是 
基于 TCP 实 现 的 ， 那 么 upstream 机 制 都 是 适用 的 。 基 于 TCP 的 响应 其 实 
就 是 有 顺序 的 数据 流 ， 那 么 ，upstream 机 制 只 需要 按照 接收 到 的 顺序 调 
用 HTTP 模 块 来 解析 数据 流 不 就 行 了 吗 ? 多 么 简单 和 清晰 ! 然而 ， 实 际 
上 ， 应 用 层 协议 要 比 这 复杂 得 多 ， 这 主要 表现 在 协议 长 度 的 不 可 确定 和 
协议 内 容 的 解析 上 上。 首先， 应 用 层 协 议 的 啊 应 包 可 大 可 小 ， 如 最 小 的 啊 
应 可 能 只 有 128B， 最 大 的 啊 应 可 能 达到 5GB， 如 果 属 于 HTTP 框 架 的 
ngx_http_upstream_module 模 块 在 内 存 中 接收 到 全 部 响应 内 容 后 再 调用 
各 个 HTTP 模 块 处 理 啊 应 ， 就 很 容易 引发 OutOfMemory 错 误 ， 即 使 没有 
错误 也 会 因为 内 存 消耗 过 大 从 而 降低 了 并 发 处 理 能 力 。 如 果 在 磁盘 文件 
中 接收 全 部 响应 ， 又 会 带 来 大 量 的 磁盘 IO 操作 ， 最 终 大 幅 提高 服务 器 











的 负载 。 其 次 ， 对 啊 应 中 的 所 有 内 容 痢 进行 解析 并 无 必要 解析 操作 毕 
况 对 CPU 是 有 消耗 的 ) 。 例 如 ， 从 Memcached 服 务 器 上 下 载 一 幅 图 片 ， 
Nginx 只 需要 解析 Memcached 协 议 ， 并 不 需要 解析 图 片 的 内 容 ， 对 于 图 
片 内 容 ，Nginx 只 需要 边 接收 边 转发 给 客户 端 即 可 。 


为 了 解决 上 述 问题 ， 应 用 层 协 议 通常 都 会 将 请 求 和 响应 分 成 两 部 
分 : 包头 和 包 体 ， 其 中 包头 在 前 而 包 体 在 后 。 包 头 相当 于 把 不 同 的 协议 
包 之 间 的 共同 部 分 抽象 出 来 ， 不 同 的 数据 包 之 间 包 头 都 具备 相同 的 格 
式 ， 服 务 器 必须 解析 包头 ， 而 包 体 则 完全 不 做 格式 上 的 要 求 ， 服 务 器 是 
否 解析 它 将 视 业 务 上 的 需要 而 定 。 包 头 的 长 度 要 么 是 固定 大 小 ， 要 么 是 
限制 在 一 个 数值 以 内 《例如 ， 类 似 Apache 这 样 的 web 服 务 器 默认 情况 下 
仅 接收 包头 小 于 4KB 的 HITP 请 求 ) ， 而 包 体 的 长 度 则 非常 灵活 ， 可 以 
非常 大 ， 也 可 以 为 0。 对 于 Nginx 服 务 器 来 说 ， 在 process_header 处 理 包头 
时 ， 需 要 开辟 的 内 存 大 小 只 要 能 够 容纳 包头 的 长 度 上 限 即 可 ， 而 处 理 包 
体 时 需要 开辟 的 内 存 大 小 情况 较 复 杂 ， 可 参见 12.6 节 ~12.8。 





包头 和 包 体 存储 什么 样 的 信息 完全 取决 于 应 用 层 协议 ， 包 头 中 的 信 








序列 号 等 信息 ， 这 些 是 upstream 机 制 并 不 关心 的 ， 它 已 经 在 
ngx_http_upstream_t 结 构 体 中 抽象 出 了 process_header 方 法 ， 由 具体 的 
HTTP 模 块 实现 的 process_header 来 解析 包头 。 实 际 上 ，upstream 机 制 并 


没有 对 HTTP 模 块 怎样 实现 process_header 方 法 进行 限制 ， 但 如 果 HTTP 模 
块 的 目的 是 实现 反 向 代理 ， 不 妨 将 接收 到 的 包头 按照 上 游 的 应 用 层 协议 
与 HITP 的 关系 ， 把 解析 出 的 一 些 头 部 适 配 到 ngx_http_upstream_t 结 构 体 
中 的 headers_in 成 员 中 ， 这 样 ，upstream 机 制 在 图 12-5 的 第 8 步 就 会 自动 
地 调用 ngx_http_upstream_process_headers 方 法 将 这 些 头 部 设置 到 发 送 给 
下 游客 户 端的 HTTP 响 应 包头 中 。 





包 体 的 内 容 往往 较为 简单 ， 当 HTTP 模 块 希望 实现 反 向 代理 功能 时 
大 都 不 希望 解析 包 体 。 这 样 的 话 ，upstream 机 制 基于 这 种 最 常见 的 需 
求 ， 把 包 体 的 常见 处 理 方 式 抽象 出 3 类 加 以 实现 ，12.5.2 节 中 将 介绍 这 3 
种 包 体 的 处 理 方式 。 





12.5.2 ”处 理 包 体 的 3 种 方式 








为 什么 upstream 机 制 不 是 仅仅 负责 接收 上 游 服 务 吉 发 来 的 包 体 ， 再 
交 由 HTTP 模 块 决 定 如 何 处 理 这 个 包 体 呢 ? 这 是 因为 upstream 有 一 个 最 重 
要 的 使 命 要 完成 ! Nginx 作 为 一 个 试图 取代 Apache 的 Web 服 务 器 ， 最 基 
本 的 反 向 代理 功能 是 必须 存在 的 ， 而 实现 反 向 代理 的 Web 服 务 器 并 不 仅 
仅 和 希望 可 以 访问 上 游 服 务 器 ， 它 更 希望 upstream 能 够 实现 透 传 、 转 及 上 
游 响 应 的 功能 。 





upstream 机 制 不 关心 如 何 构造 发 送 到 上 游 的 请 求 内 容 ， 这 事实 上 是 


由 各 个 使 用 upstream 的 HTTP 模 块 实现 的 create_request 方 法 决定 的 (目前 
的 HTTP 反 向 代理 模块 是 这 么 做 的 : Nginx 将 客户 端的 请 求全 部 接收 后 再 
透 传 给 上 游 服务 器 ， 这 种 方式 很 简单 ， 叉 对 减轻 上 游 服务 喜 的 并 及 负载 
很 有 帮助 ) ， 但 对 响应 的 处 理 就 比较 复杂 了 ， 下 面 举 两 个 例子 来 说 明 其 
复杂 性 。 








如 果 Nginx 与 上 游 服 务 器 间 的 网 速 很 快 ( 例 如， 两 者 都 在 一 个 机 房 
的 内 网 中 ， 或 者 两 者 间 拥 有 专线 ) ， 而 Nginx 与 下 游 的 客户 站 间 网 速 勾 
很 慢 〈( 例 如 ， 下 游客 户 病 通过 公 网 访问 机 房 内 的 Nginx〉， 这 样 就 会 导 
致 Nginx 接 收 上 游 服 务 器 的 响应 非常 快 ， 而 向 下 游客 户 端 转发 响应 时 很 
慢 ， 这 也 就 为 upstream 机 制 币 来 一 个 需求 : 应 当 尽 可 能 地 把 上 游 服务 器 
的 响应 接收 到 Nginx 服 务 器 上 ， 包 括 将 来 自 上 游 的 、 还 没 来 及 发 送 到 下 
游 的 包 体 缓存 到 内 存 中 ， 如 果 使 用 的 内 存 过 大 ， 达 到 某 个 限制 浆 值 后 ， 
为 了 降低 内 存 的 消耗 ， 还 需要 把 包 体 缓存 到 磁盘 文件 中 。 





如 果 Nginx 与 上 游 服 务 器 间 的 网 速 较 慢 〈 假 设 是 公 网 线路 ) ， 
Nginx 与 下 游 的 客户 端 间 的 网 速 很 快 〈 例 如 ， 客 户 端 其 实 是 Nginx 所 在 机 
房 里 的 另 一 个 Web 服务器 ) ， 这 时 就 不 在 在 大 量 缓存 上 游 响应 的 需求 
了 ， 完 全 可 以 开辟 一 块 固定 大 小 的 内 存 作为 缓冲 区 ， 一 边 接收 上 游 响 
应 ， 一 边 向 下 游 转 发 。 每 当 向 下 游 成 功 转发 部 分 响应 后 就 可 以 复 用 缓冲 
区 ， 这 样 既 不 会 消耗 大 量 内 存 〈 增 加 Nginx 并 发 量 ) ， 又 不 会 使 用 到 磁 
盘 IO (减少 了 用 户 等 待 响应 的 时 间 〉。 














因此 ，upstream 机 制 提供 了 3 种 处 理 包 体 的 方式 : 不 转发 响应 〈 即 不 
实现 反问 代理 ) 、 转 发 啊 应 时 以 下 游 网 速 优先 、 转 发 响应 时 以 上 游 网 速 
优先 。 怎 样 告 诉 upstream 机 制 使 用 哪 种 方式 处 理 上 游 的 啊 应 包 体 呢 ? 当 
请 求 ngx_http_request_t 结 构 体 的 subrequest_in_memory 标 志 位 为 1 时 ， 将 
采用 第 1 种 方式 ， 即 不 转发 响应 ， 当 subrequest_in_memory 为 0 时 ， 将 转 
发 响应 。 而 ngx_http_upstream_conf t 配 置 结构 体 中 的 buffering 标 志 位 ， 
会 决定 转发 响应 时 是 否 开局 更 多 的 内 存 和 磁盘 文件 用 于 缓存 上 游 响 应 ， 
如 果 buffering 为 0， 则 以 下 游 网 速 优先 ， 使 用 固定 大 小 的 内 存 作为 组 
存 ; 如 果 buffering 为 1， 则 以 上 游 网 速 优先 ， 使 用 更 多 的 内 存 、 硬 盘 文 
件 作为 缓存 。 


1. 不 转发 啊 应 





不 转发 包 体 是 upstream 机 制 最 基本 的 功能 ， 特 别 是 客户 端 请 求 派生 
出 的 子 请 求 多 半 不 需要 转发 包 体 ，upstream 机 制 的 最 低 目标 就 是 允许 
HTTP 模 块 以 TCP 访 问 上 游 服务 器 ， 这 时 HTTP 模块 仅 希 望 解析 包头 、 包 
体 ， 没 有 转发 上 游 响应 的 需求 。upstream 机 制 提 供 的 解析 包头 的 回调 方 
法 是 process_header， 而 解析 包 体 的 回调 方法 则 是 input_filter。 在 12.6 节 
将 会 描述 这 种 处 理 包 体 的 最 基本 方式 是 如 何 工作 的 。 








2. 转 发 啊 应 时 下 游 网 速 优 先 





在 转发 啊 应 时 ， 如 果 下 游 网 速 快 于 上 游 网 速 ， 或 者 它们 速度 相差 不 


大 ， 这 时 不 需要 开辟 大 块 内 存 或 者 磁盘 文件 来 缓存 上 游 的 响应 。 我 们 将 
在 12.7 节 中 讲述 这 种 处 理 方式 下 upstream 机 制 是 如 何 工 作 的 。 


3. 转 发 啊 应 时 上 游 网 速 优先 


在 转发 啊 应 时 ， 如 条 上 游 网 速 快 于 下 游 网 速 〈 由 于 Nginx 文 持 高 并 
发 特性 ， 所 以 大 多 数 时 候 都 用 于 做 最 前 端的 Web 服 务 硕 ， 这 时 上 游 网 速 
都 会 快 于 下 游 网 速 》， 这 时 需要 开辟 内 存 或 者 磁盘 文件 缓存 来 自 上 游 服 
务 器 的 啊 应 ， 注 意 ， 绥 存 可 能 会 非常 大 。 这 种 处 理 方式 比较 复杂 ， 在 


12.8 市 中 我 们 会 详细 描述 其 主要 流程 。 


12.5.3 ”接收 啊 应 头 部 的 流程 


下 面 开 始 介绍 读 取 上 游 服 务 器 响应 的 
ngx_http_upstream_process_header 方 法 ， 这 个 方法 主要 用 于 接收 、 解 析 
吧 应 头 部 ， 当 然 ， 由 于 upstream 机 制 是 不 涉及 应 用 层 协 议 的 ， 谁 使 用 了 
upstream 谁 就 要 负责 解析 应 用 层 协议 ， 所 以 必须 由 HTTP 模 块 实现 的 
process_header 方 法 解析 啊 应 包头 。 当 包头 接收 、 解 析 完 毕 后， 
ngx_http_upstream_process_header 方 法 还 会 决定 以 哪 种 方式 处 理 包 体 

《参见 12.5.2 节 中 介绍 的 3 种 包 体 处 理 方式 ) 。 





在 接收 啊 应 包头 的 阶段 中 ， 处 理 连 接 读 事 件 的 方法 始终 是 
ngXx_http_Upstream_process_header， 也 就 是 说 ， 该 方法 会 反复 被 调用 ， 


在 研究 其 流程 时 需要 特别 注意 。 图 12-5 描 述 了 它 的 主要 流程 。 


1) 检查 读 事 件 
的 有 效 性 
[接收 响应 超时 或 者 还 未 发 送 请 求 给 上 游 ] 


[ 读 事 件 可 用 , 再 检查 buffer 接收 缓冲 区 是 否 可 用 ] 


2) 调用 ngx_http_upstream_next 














方法 重 试 或 结束 


[如 果 buffer 绥 冲 区 未 分 配 ] 


[连接 关闭 


或 者 错误 ] 
4) 调 用 recv 
方法 读 取 缓冲 区 
[检查 recv 返 回 值 ] 
[返回 NGX_AGAIN] 





[buffer 绥 冲 区 用 尽 ] 
[返回 NGX_HTTP_UPSTREAM_INVALID_HEADERI] 


[ 读 取 到 响应 ] 


6 ) 调 用 process_header 





方法 解析 响应 包头 
冲 区 ] [检查 process] eader 返回 值 ] 


5 ) 将 读 事件 
a | | [返回 NGX_ERRORI] 添加 到 epoll 中 


[返回 NGX_AGAN 后 ， 肯 检查 buffer 是 否 全 部 用 尽 ] 
[返回 Ncx om 


[有 空闲 绥 


7) 调 用 ngx_http_upstream_finalize_request 


方法 结束 请 求 






8) 调用 ngx_http_upstream_process_headers 
方法 处 理 headers_in 
[检测 subrequest in_memory 标志 位 ,确认 是 否 需 要 转发 包 体 ] 


subrequest_in_memory 为 0] 9) 调 用 ngx_http_upstream_send_response 


方法 转发 响应 





[subrequest_ in_memory 为 1, 不 转发 响应 ] 
10) 初始 化 过 滤 
包 体 的 方法 
[检测 buffer 中 是 和 否 已 经 接收 到 包 体 ] 
(buffer 中 已 含有 包 体 ] 


<7 


[buffer 中 未 含有 和 包 体 ] 


12) 重新 设置 
read_event_handler 


13) 调用 ngx_http_upstream_process_body_in_memory 

















用 input_filter 


方法 处 理 已 接收 到 的 包 体 











方法 处 理 包 体 


图 12-5 ngx_http_upstream_process_headet 方 法 的 流程 图 


下 面 详细 介绍 图 12-5 中 的 13 个 步骤 。 











1) 首先 检查 读 事件 是 否 有 效 ， 包 括 检查 timedout 标 志 位 是 否 为 1， 
如 果 timedout 为 1， 则 表示 读 取 啊 应 已 经 超时 ， 这 时 跳 到 第 2 步调 用 
ngx_http_upstream_next 方 法 决定 下 一 步 的 动作 ， 其 中 传递 的 参数 是 
NGX_HTTP_UPSTREAM_FT_TIMEOUT。 如 果 timedout 为 0， 则 继续 检 
查 request_sent 标 志 位 。 如 果 request_sent 为 0， 则 表示 还 没有 发 送 请 求 到 
上 游 服 务 器 束 收 到 来 目 上 游 的 啊 应 ， 不 符合 upstream 的 设计 场景 ， 这 时 
仍然 跳 到 第 2 步调 用 ngx_http_upstream_next 方 法 ， 传 递 的 参数 是 
NGX_HTTP_UPSTREAM_FT_ERROR。 如 果 读 事件 完全 有 效 ， 则 跳 到 








第 3 步 执行 。 


2) 只 有 请 求 触发 了 失败 条 件 后 ， 才 会 执行 hgx_http_upstream_next 
方法 ， 该 方法 将 会 根据 配置 信息 决定 下 一 步 究 竟 是 重新 发 起 upstream 请 
求 ， 还 是 结束 当前 请 求 ， 在 12.9.2 节 会 详细 说 明 该 方法 的 工作 流程 。 当 
前 读 事件 处 理 完毕 。 

















3) 检查 ngx_http_upstream_t 结 构 体 中 接收 响应 头 部 的 buffer 绥 冲 
区 ， 如 果 它 的 start 成 员 指 向 NULL， 说 明 缓 冲 区 还 未 分 配 内 存 ， 这 时 将 
按照 ngx_http_upstream_conf t 配 置 结 构 体 中 的 buffer_size 成 员 指 定 的 大 
小 来 为 buffer 缓 冲 区 分 配 内 存 。 





4) 调用 recv 方 法 在 buffer 绥 冲 区 中 读 取 上 游 服 务 器 发 来 的 啊 应 。 检 


测 recv 方 法 的 返回 值 ， 有 3 类 返回 值 会 导致 3 种 不 同 的 结果 : 如 果 返 回 
NGX_AGAIN， 则 表示 还 需要 继续 接收 响应 ， 这 时 跳 到 第 5 步 执行 ， 如 
果 返 回 0 (表示 上 游 服 务 器 主动 关闭 连接 ) 或 者 返回 NGX_ERROR， 这 
时 跳 到 第 2 步 执行 hgx_http_upstream_next 方 法 ， 传 递 的 参数 是 
NGX_HTTP_UPSTREAM_FT_ERROR; 如 果 返 回 正 数 ， 这 时 该 数值 表 
示 接 收 到 的 响应 长 度 ， 跳 到 第 6 步 处 理 响应 。 





5) 调用 ngx_handle _read_event 方 法 将 读 事 件 再 添加 到 epoll 中 ， 等 竺 
读 事件 的 下 次 触发 。ngx_http_upstream_process_header 方 法 执行 完毕 。 


6) 调用 HTTP 模 块 实现 的 process_header 方 法 解析 响应 头 部 ， 检 测 其 
返回 值 : 返回 NGX_HTTP_UPSTREAM_INVALID_HEADER 表 示 包 头 
不 合法 ， 这 时 跳 到 第 2 步调 用 ngx_http_upstream_next 方 法 ， 传 递 的 参数 
是 NGX_HTTP_UPSTREAM_FT_INVALID_HEADER; 返回 
NGX_ERROR 表 示 出 现 错误 ， 直 接 跳 到 第 7 步 执行 ， 返 回 NGX_OK 表 示 
解析 到 完整 的 包头 ， 这 时 跳 到 第 8 步 执 行 ， 返回 NGX_AGAIN 表 示 包 头 
还 没有 接收 完整 ， 这 时 将 检测 buffer 组 冲 区 是 否 用 尽 ， 如 果 缓 冲 区 已 经 
用 尽 ， 则 说 明 包 头 太 大 了 ， 超 出 了 缓冲 区 允许 的 大 小 ， 这 时 跳 到 第 2 步 
调用 ngx_http_upstream_next 方 法 ， 传 递 的 参数 依然 是 
NGX_HTTP_ UPSTREAM_FT_INVALID_HEADER， 其 表示 包头 不 合 
法 ， 而 如 果 缓 冲 区 还 有 空空 间 ， 则 返回 第 4 步 继 续 接收 上 游 服 务 器 的 
啊 应 。 








7) 调用 ngx_http_upstream_finalize_request 方 法 结束 请 求 〈 详 见 


12.9.3 节 ) ，ngx_http_upstream_process_header 方 法 执行 完毕 。 


8) 调用 ngx_http_upstream_process_headers 方 法 处 理 已 经 解析 出 的 
头 部 ， 该 方法 将 会 把 已 经 解析 出 的 头 部 设置 到 请 求 ngx_http_request_ {t 结 
构 体 的 headers_out 成 员 中 ， 这 样 在 调用 ngx_http_send_header 方 法 发 送 啊 
应 包头 给 客户 端 时 将 会 发 送 这 些 设 置 了 的 头 部 。 











接 下 来 检查 是 否 需要 转发 啊 应 ，ngx_http_request_t 结 构 体 中 的 
subrequest_in_memory 标 志 位 为 1 时 表示 不 需要 转发 啊 应 ， 跳 到 第 10 步 执 
行 ，subrequest_in_memory 为 0 时 表示 需要 转发 响应 到 客户 端 ， 跳 到 第 9 


步 执行 。 


9) 调用 ngx_http_upstream_send_response 方 法 开始 转发 啊 应 给 客户 


端 ， 同 时 ngx_http_upstream_process_header 方 法 执行 完毕 。 





10) 首先 检查 HTTP 模 块 是 否 实现 了 用 于 处 理 包 体 的 input_filter 方 
法 ， 如 果 没 有 实现 ， 则 使 用 upstream 定 义 的 默认 方法 
ngx_http_upstream_non_buffered_filter 代 蔡 input_filter， 其 中 
input_filter_ctx 将 会 被 设置 为 ngx_http_request_t 结 构 体 的 指针 。 如 果 用 户 
己 经 实现 了 input_filter 方 法 ， 则 表示 用 户 希 望 自己 处 理 包 体 (如 
ngx_http_memcached_module 模 块 )， 这 时 首先 调用 input_filter_init 方 法 
为 处 理 包 体 做 初始 化 工作 。 





11) 在 第 6 步 的 process_ header 方 法 中 ， 如 果 解 析 完 包头 后 绥 锌 区 中 
还 有 多 余 的 字符 ， 则 表示 还 接收 到 了 包 体 ， 这 时 将 调用 input_filter 方 法 
第 一 次 处 理 接收 到 的 包 体 。 


12) 设置 upstream 的 read_event_handler 为 
ngx_http_upstream_process_body_in_memory 方 法 ， 这 也 表示 再 有 上 游 服 
务 器 发 来 啊 应 包 体 ， 将 由 该 方法 来 处 理 ( 参 见 12.6 广 )。 


13) 调用 ngx_http_upstream_process_body_in_memory 方 法 开始 处 理 
包 体 。 





从 上 面 的 第 12 步 可 以 看 出 ， 当 不 需要 转发 啊 应 时 ， 
ngx_http_upstream_process_body_in_memory 方 法 将 作为 读 取 上 游 服 务 器 
包 体 的 回调 方法 。 什 么 时 候 无 须 转发 包 体 呢 ? 在 subrequest_in_memory 
标志 位 为 1 时 ， 实 际 上 ， 这 也 意味 着 当前 请 求 是 个 subrequest 子 请 求 。 也 
就 是 说 ， 在 通常 情况 下 ， 如 果 来 自 客户 端的 请 求 直接 使 用 upstream 机 
制 ， 那 都 需要 将 上 游 服 务 器 的 响应 直接 转发 给 客户 端 ， 而 如 果 是 客户 端 
请 求 派生 出 的 子 请 求 ， 则 不 需要 转发 上 游 的 响应 。 因 此 ， 当 我 们 开发 
HTTP 模 块 实现 某 个 功能 时 ， 若 需要 访问 上 游 服务 器 获取 一 些 数据 ， 那 
么 可 开发 两 个 HTTP 模 块 ， 第 一 个 HTTP 模 块 用 于 处 理 客 户 端 请 求 ， 当 它 
需要 访问 上 游 服务 器 时 就 派生 出 子 请 求 访问 ， 第 二 个 HITP 模 块 则 专用 
于 访问 上 游 服 务 器 ， 在 子 请 求解 析 完 上 游 服务 器 的 啊 应 后 ， 再 激活 父 请 
求 处 理 客 户 端 要 求 的 业务 。 














人 @@ 注音。 以 上 描述 的 开发 场景 是 Nginx 推 荐 用 户 使 用 的 方式 ， 虽 然 
可 以 通过 任意 地 修改 subrequest 标 志 位 来 更 改 以 上 特性 ,但 目前 这 种 设计 
对 于 分 离 关 注 点 还 是 非常 有 效 的 ， 是 一 种 很 好 的 设计 模式 ， 如 无 必要 最 
好 不 要 更 改 。 





从 上 面 的 第 9 步 可 以 看 出 ， 当 需要 转发 包 体 时 将 调用 
ngx_http_upstream_send_response 方 法 来 转发 包 体 。 
ngx_http_upstream_send_response 方 法 将 会 根据 ngx_http_upstream_conf t 
配置 结构 体 中 的 buffering 标 志 位 来 决定 是 否 打 开 绥 存 来 处 理 啊 应 ， 也 就 
是 说 ，buffering 为 0 时 通常 会 默认 下 游 网 速 更 快 ， 这 时 不 需要 缓存 啊 应 

《在 12.7 节 中 将 会 介绍 这 一 流程 ) 。 如 果 buffering 为 1， 则 表示 上 游 网 速 
更 快 ， 这 时 需要 用 大 量 内 存 、 人 磁盘 文件 来 缓存 来 自 上 游 的 啊 应 (在 12.8 





12.6 不 转发 啊 应 时 的 处 理 流程 


实际 上 ， 这 里 的 不 转发 啊 应 只 是 不 使 用 upstream 机 制 的 转发 啊 应 功 
能 而 已 ， 但 如 果 HTTP 模 块 有 意愿 转发 啊 应 到 下 游 ， 还 是 可 以 通过 
input_filter 方 法 实现 相关 功能 的 。 





当 请 求 属于 subrequest 子 请 求 ， 且 要 求 在 内 存 中 人 处 理 包 体 时 (在 第 5 
章 介绍 过 ngx_http_subrequest 方 法 ， 通 过 它 派生 子 请 求 时 ， 可 以 将 最 后 
一 个 flag 参 数 设 置 为 NGX_HTTP_SUBREQUEST_IN_MEMORY 宏 ， 这 
样 就 将 ngx_http_request_t 结 构 体 中 的 subrequest_in_memory 标 志 位 设 为 1 
了 ) ， 束 会 进入 本 市 插 述 的 不 转发 啊 应 这 个 流程 。 或 者 通过 主动 设置 
subrequest_in_memory 标 志 位 为 1 也 可 以 做 到 ， 当 然 并 不 推荐 这 样 做 。 为 
什么 呢 ? 因为 不 需要 转发 啊 应 时 的 应 用 场景 通常 如 下 : 业务 需求 导致 需 
要 综合 上 游 服务 器 的 数据 来 重新 构造 发 往 客户 端的 响应 ， 如 从 上 游 的 数 
据 库 或 者 Tomcat 服 务 器 中 获取 用 户 权 限 信息 等 。 这 时 ， 根 据 Nginx 推 荐 
的 设计 模式 ， 应 当 由 原始 请 求 处 理 客户 端的 请 求 ， 并 派生 出 子 请 求 访问 
上 游 服务 器 ， 在 这 种 场景 下 ， 一 般 会 布 望 在 内 存 中 解析 上 游 服 务 占 的 啊 
应 。 

















乱 ) 放 入 实 ， 在 内 存 中 处 理 上 游 响应 的 包 体 也 有 两 种 方式 ， 第 
一 种 方式 接收 到 全 部 的 包 体 后 再 开始 处 理 ， 第 二 种 方式 是 每 接收 到 一 部 


分 响应 后 就 处 理 这 一 部 分 。 第 一 种 方式 可 能 浪费 大 量 内 存 用 于 接收 完整 
的 响应 包 体 ， 第 二 种 方式 则 会 始终 复 用 同一 块 内 存 缓冲 区 。HTTP 模 块 
可 以 自由 地 选择 使 用 哪 种 方式 。 


ngx_http_upstream_process_body_in_memory 就 是 在 upstream 机 制 不 
转发 响应 时 ， 作 为 读 事件 的 回调 方法 在 内 存 中 处 理 上 游 服务 器 响应 包 体 
的 。 每 次 与 上 游 的 TCP 连 接 上 有 读 事 件 触及 时 ， 它 都 会 被 调用 ，HTTP 
模块 通过 重新 实现 input_filter 方 法 来 处 理 包 体 ， 在 12.6.1 节 中 会 讨论 如 何 
实现 这 个 回调 方法 ， 如果 HTTP 模 块 不 实现 input filter 方法， 那么 
upstream 机 制 就 会 自动 使 用 默认 的 ngx_http_upstream_non_buffered_filter 
方法 来 处 理 包 体 ， 在 12.6.2 节 中 会 讨论 这 个 默认 的 input_filter 方 法 做 了 些 
什么 ; 在 12.6.3 节 中 将 会 具体 分 析 
ngx_http_upstream_process_body_in_memory 方 法 的 工作 流程 。 


12.6.1 input_filter 方 法 的 设计 


先 来 看 一 下 input_filter 回 调 方法 的 定义 ， 如 下 所 示 。 





ngx_int_t (*input_filter)(void *data, ssize_t bytes ) 





其 中 ，bytes 参 数 是 本 次 接收 到 的 包 体 长 度 。 而 data 参 数 却 不 是 指 问 
接收 到 的 包 体 的 ， 它 实际 上 是 在 启动 upstream 机 制 之 前 ， 所 设置 的 
ngx_http_upstream _t 结 构 体 中 的 input_filter_ctx 成 员 ， 下 面 看 一 下 它 的 定 


void *input_filter_ctx; 


它 被 设计 为 可 以 指 癌 任 意 结构 体 ， 其 实 束 是 用 来 传递 参数 的 。 因 为 
在 内 存 中 人 处理 包 体 时 ， 可 能 需要 一 个 结构 体 作为 上 下 文 存储 状态 、 结 果 
等 一 些 信 息 ， 这 个 结构 体 必须 在 启动 upstream 机 制 前 设置 。 同 时 ， 在 处 
理 包 体 前 ， 还 会 调用 一 次 input_filter_init 方 法 (HTTP 模块 如 果 需 要 在 开 
始 接收 包 体 时 初始 化 变量 ， 都 会 在 这 个 方法 中 实现 ) ， 下 面 看 一 下 它 的 
定义 。 











ngx_int_t (*input_filter_init)(void *data); 


data 参 数 意义 同上 ， 仍 然 是 input_filter_ctx 成 员 。 


下 面 将 重点 讨论 如 何在 input_filter 方 法 中 处 理 包 体 。 首 先 要 弄 清 楚 
征 从 哪里 获取 到 本 次 接收 到 的 上 游 啊 应 包 体 。 答 案 是 可 由 ngx_buf t 类 型 
的 buffer 绥 冲 区 获得 。buffer 绥 冲 区 中 的 last 成 员 指 辐 本 次 接收 到 的 包 体 
的 起 始 地 址 ， 而 input_filter 方 法 的 bytes 参 数 表 明了 本 次 接收 到 包 体 的 字 
节 数 。 通 过 buffer->last 和 bytes 获 取 到 本 次 接收 到 的 包 体 后 ， 下 面 的 工作 
就 是 由 HTTP 模 块 处 理 接收 到 的 包 体 。 





在 处 理 完 这 一 次 收 到 的 包 体 后 ， 需 要 告诉 buffer 缓 冲 区 已 经 处 理 过 
刚 接收 到 的 包 体 吗 ? 这 就 需要 看 业务 需求 了 。 


如 果 我 们 需要 反复 使 用 buffer 绥 冲 区 ， 即 buffer 指 向 的 这 块 内 存 需 
复 用 ， 或 者 换 名 话说， 下 次 接收 到 的 响应 将 会 覆盖 buffer 上 刚刚 接收 到 
的 响应 ， 那 么 input_filter 方 法 被 调用 时 必须 处 理 完 buffer 缓 冲 区 中 的 全 部 
内 容 ， 这 种 情况 下 不 需要 修改 buffer 缓 冲 区 中 的 成 员 。 当 再 次 接收 到 后 
续 的 包 体 时 ， 将 会 继续 从 buffer->last 指 向 的 内 存 地 址 处 覆盖 上 次 的 包 体 
内 容 。 





如 果 我 们 希望 buffer 组 种 区 保存 部 分 或 者 全 部 的 包 体 ， 则 需要 进行 
针对 性 的 处 理 。 我 们 知道 ， 在 ngx_buf t 表 示 的 缓冲 区 中 ，start 和 end 成 
员 圈 定 了 缓冲 区 的 可 用 内 存 ， 这 对 于 buffer 缓 冲 区 来 说 同样 成 立 ，last 成 
员 将 指向 接收 到 的 上 游 服务 器 的 响应 包 体 的 起 始 内 存 地 址 。 因 此 ， 自 由 
地 移动 last 指 针 就 是 在 改变 buffer 缓 冲 区 。 例 如 ， 如 果 和 希望 buffer 缓 冲 区 
存储 全 部 包 体内 容 ， 那 么 不 妨 把 last 指 针 向 后 移动 bytes 字 节 〈 参 见 12.6.2 

) ; 如 果 希 望 buffer 缓 冲 区 尽 可 能 地 接收 包 体 ， 等 缓冲 区 满 后 再 从 头 
接收 ， 那 么 可 以 检测 last 指 针 ， 在 last 未 达到 end 指 针 的 位 置 时 可 以 继续 
向 后 移动 ， 直 到 last 到 达 end 指 针 处 ， 在 到 达 end 指 针 后 可 以 把 last 指 针 指 
向 start 成 员 ， 这 样 又 会 重头 复 用 这 块 内 存 了 。 











input_filter 的 返回 值 非常 简单 ， 只 要 不 是 返回 NGX_ERROR， 就 都 
认为 是 成 功 的 ， 当 然 ， 不 出 错时 最 好 还 是 返回 NGX_OK。 如 果 返 回 
NGX_ERROR， 则 请 求 会 结束 ， 参 见 图 12-6。 








12.6.2 ”默认 的 input_filter 方 法 


如 果 HTTP 模 块 没有 实现 input_filter 方 法 ， 那 么 将 使 用 
ngx_http_upstream_non_buffered_filter 方 法 作为 input_filter， 这 个 默认 的 
方法 将 会 试图 在 buffer 绥 冲 区 中 存放 全 部 的 啊 应 包 体 。 


ngx_http_upstream_non_buffered_filter 方 法 其 实 很 简单 ， 下 面 直 接 列 
出 其 主要 代码 来 分 析 该 方法 。 





static ngx_int_t ngx_http_upstream non_ buffered filter(void *data, ssize t bytes) 





/* 前 文 说 过 ， 


data 参 数 就 是 


ngx_http_upstream_t 结 构 体 中 的 


input_filter_ctx,， 当 


HTTP 模 块 未 实现 


input_filter 方 法 时 ， 


input_fijter_ctx 成 员 会 指向 请 求 的 


ngx_http_request_t 结 构 体 


*/ 
ngx_http_request t *r = data,; 
ngx_buf_t *b; 
ngx_chain _t *cl, **]1; 
ngx_http_upstream t *u; 
U = r->upstream; 
/A* 找 到 


out_bufs 链 表 的 末尾 ， 其 中 


Cl 指向 链表 中 最 后 一 个 

ngx_chain_t 元 素 的 

next 成 员 ， 所 以 

Cl 最 后 一 定 是 

NULL 空 指针 ， 而 

1】 指向 最 后 一 个 缓冲 区 的 地 址 ， 它 用 来 在 后 面 的 代码 中 向 
out_bufs 链 表 添 加 新 的 缓冲 区 


*/ 
for (cl = u->out_bufs, 11 = &u->out_bufs; cl; cl = cl->next) 


11 = &cl->next; 

J 
ngx_buf_t 结 构 体 构 成 的 链表 ， 如 果 
free_bufs 此 时 是 空 的 ， 那么 将 会 重新 由 
r->po01 内 存 池 中 分 配 一 个 
ngx_buf 七 结构 体 给 
Cl; 如 果 
free_bufs 链 表 不 为 空 ， 则 直接 由 
free_bufs 中 获取 一 个 


ngx_buf 七 结构 体 给 


cl1*/ 
cl = ngx_chain get free buf(r->pool, &u->free_bufs); 
if (cl == NULL) { 
return NGX_ERROR; 





} 
// 将 新 分 配 的 


ngx_buf t 结 构 体 添加 到 


out_bufs 链 表 的 末尾 


*11 = cl; 
/* 修 改 新 分 配 缓冲 区 的 标志 位 ， 表 明 在 内 存 中 ， 


flush 标 志 位 为 可 能 发 送 缓冲 区 到 客户 端 服务 ， 参 


己 


42.7 芝 


*/ 
cl->buf->flush = 1; 
cl->buf->memory = 1; 
// buffer 缓 冲 区 才 是 真正 接收 上 游 服务 器 响应 包 体 的 缓冲 区 


b = &u->buffer 
// last 实 际 指向 本 次 接收 到 的 包 体 首 地 址 


cl->buf->pos = b->last; 
// last 向 后 移动 


bytes 字 节 ， 意 味 着 


buffer 需 要 保存 这 次 收 到 的 包 体 


b->last += bytes; 
// last 和 和 


pos 成 员 确 定 了 


Out_bufs 链 表 中 每 个 缓冲 区 的 包 体 数据 


cl->buf->last = b->last,; 
cl->buf->tag = U->output tag; 
/* 如 果 没 有 设置 包 体 长 度 ， 


U->length 就 是 


NGX_MAX_SIZE_T_VALUE， 那 么 到 这 里 结束 


*/ 
if (u->length == NGX_MAX_SIZE_T_VALUE) { 
return NGX_OK; 


} 
// 更 新 
length， 需 要 接收 到 的 包 体 长 度 减 少 


bytes 字 节 
u->length -= bytes; 


return NGX_OK; 
} 





可 以 看 到 ， 默 认 的 input_filter 方 法 会 试图 让 独立 的 buffer 绥 冲 区 保存 
全 部 的 包 体 ， 这 就 要 求 我 们 对 上 游 服务 器 的 响应 包 体 大 小 有 绝对 正确 的 
判断 ， 否 则 一 旦 上 游 服务 器 发 来 的 响应 包 体 超过 buffer 缓 冲 区 的 大 小 ， 
请 求 将 会 出 错 。 


@ i 对 于 上 述 这 段 代码 的 理解 ， 可 参见 图 12-8 第 4 步 中 


negx_chain_update_chains 方 法 的 执行 过 程 ， 它 们 是 配对 执行 的 。 
12.6.3 ”接收 包 体 的 流程 


本 节 介 绍 的 实际 就 是 ngx_http_upstream_process_body_in_memory 方 
法 的 执行 流程 ， 它 会 负责 接收 上 游 服 务 器 的 包 体 ， 同 时 调用 HTTP 模 块 
实现 的 input_filter 方 法 处 理 包 体 ， 如 图 12-6 所 示 。 


下 面 分 析 图 12-6， 了 解 一 下 在 内 存 中 处 理 包 体 的 流程 。 


1) 首先 要 检查 Nginx 接 收 上 游 服 务 器 的 响应 是 否 超时 ， 也 就 是 检查 
读 事件 的 timedout 标 志 位 。 如 果 timedout 为 1， 则 表示 读 取 响应 超时 ， 这 
时 跳 到 第 2 步调 用 ngx_http_upstream_finalize_request 方 法 结束 请 求 ， 传 递 
的 参数 是 NGX_ETIMEDOUT ( 详 见 12.9.3 节 〉; 如 果 timedout 为 0， 则 继 


续 执 行 第 3 步 。 


2) 调用 ngx_http_upstream_finalize_request 方 法 结束 请 求 ， 该 方法 类 
似 于 ngx_http_finalize_request 方 法 ， 它 们 都 需要 一 个 rc 参数 ， 来 决定 该 
方法 的 行为 。 





3) 在 保存 着 响应 包 体 的 buffer 绥 冲 区 中 ，last 成 员 指 问 空 内 内 存 块 
的 地 址 (下 次 还 会 由 last 处 开始 接收 响应 包 体 ) ， 而 end 成 员 指向 缓冲 区 
的 结尾 ， 用 end-last 即 可 计算 出 剩余 空 闪 内存。 如 果 缓 冲 区 全 部 用 尽 ， 则 
跳 到 第 2 步调 用 ngx_http_upstream_finalize_request 方 法 结束 请 求 ， 如 果 还 
有 空闲 缓冲 区 ， 则 跳 到 第 4 步 接收 包 体 。 


4) 调用 recv 方 法 接收 上 游 服务 器 的 啊 应 ， 接 收 到 的 内 容 存放 在 
buffer 绥 冲 区 的 last 成 员 指 向 的 内 存 中 。 检 查 recv 的 返回 值 ， 不 同 的 返回 
值 会 导致 3 种 结果 : 如 果 返 回 NGX_AGAIN， 则 表示 期 待 下 一 次 的 读 事 
件 ， 这 时 跳 到 第 6 步 执行 ， 如 果 返 回 NGX_ERROR 或 者 上 游 服 务 器 主动 
关闭 连接 ， 则 跳 到 第 2 步 结束 请 求 ， 如 果 返 回 正 数 ， 则 表示 接收 到 的 啊 
应 长 度 ， 这 时 跳 到 第 5 步 处 理 包 体 。 


5) 调用 HTTP 模 块 实现 的 input_filter 方 法 处 理 本 次 接收 到 的 包 体 。 
检测 input_filter 方 法 的 返回 值 ， 返 回 NGX_ERROR 时 跳 到 第 2 步 结束 请 
求 。 否 则 ， 再 检测 读 事件 的 ready 标 志 位 ， 如 果 ready 为 1， 则 表示 仍 有 
TCP 流 可 以 读 取 ， 这 时 跳 到 第 3 步 执行 ， 如 果 ready 为 0， 则 跳 到 第 6 步 执 


/一 


介 。 
6) 调用 ngx_handle_read_event 方 法 将 读 事 件 添加 到 epoll 中 。 


7) 调用 ngx_add_timer 方 法 将 读 事件 添加 到 定时 器 中 ， 超 时 时 间 为 
ngx_http_upstream_conf t 配 置 结构 体 中 的 read_timeonut 成 员 。 


在 内 存 中 人 处理 包 体 的 关键 在 于 如 何 实现 input_filter 方 法 ， 特 别 是 在 
该 方法 中 对 buffer 缓 冲 区 的 管理 。 如 果 上 游 服务 器 的 啊 应 包 体 非常 小 ， 
可 以 考虑 本 市 说 明 的 这 种 方式 ， 它 的 效率 很 局 。 





1 ) 检查 读 事件 
是 否 超时 
[检查 读 事件 的 timedout 标 志 位 ] 








[timedout 为 1] 


[timedout 为 0] 












3) 计 算 剩余 空 
闲 缓冲 区 
[buffer 中 是 否 还 有 空闲 缓冲 区 ] 






[buffer 组 冲 区 用 尽 ] 
[buffer 缓 冲 区 还 有 空闲 空间 ] 
4) 使 用 rec 访 法 谈 取 上 游 服务 天 


发 来 的 包 体 
[ 检测 recv 返 回 值 | 





[其 楼 了 上 作 认 流 可 训 ] [出 错 或 者 上 游 服务 器 关闭 了 连接 ] 


[接收 到 包 体 ] 
[返回 NGX_AGCAIN] 5 ) 调 用 input filter 
方法 处 理 本 次 接收 的 包 体 


[检测 inputfilter 返 问 值 和 连接 是 否 仍 然 可 读 ] 
[input_filter 返 回 NGX_ERROR I] 








[ 套 接 字 上 没有 流 可 读 ] 2) 调用 ngx_http_upstream_finalize_request 


方法 结束 请 求 










6) 将 读 事件 
添加 到 epoll 中 






7) 将 读 事 件 添加 到 
定时 器 中 


图 12-6 ”ngx_http_upstream_process_body_in_memory 方 法 的 流程 图 


12.7 ”以 下 游 网 速 优先 来 转发 啊 应 





转 友 上 游 服务 器 的 啊 应 到 下 游客 尸 顺 ， 这 项 工作 必然 是 由 上 游 事 件 
来 驱动 的 。 因 此 ， 以 下 游 网 速 优先 实际 上 只 是 意味 着 需要 开辟 一 块 固定 
长 度 的 内 存 作为 缓冲 区 。 在 图 12-5 的 第 9 步 中 会 调用 
ngx_http_upstream_send_response 方 法 加 客户 端 转发 啊 应 ， 在 该 方法 中 将 
会 判断 buffering 标 志 位 ， 如 果 buffering 为 1， 则 表明 需要 打开 缓冲 区 ， 这 
时 将 会 优先 考虑 上 游 网 速 ， 尽 可 能 多 地 接收 上 游 服务 器 的 啊 应 到 内 存 或 
者 磁盘 文件 中 ， 而 如 果 buffering 为 0， 则 只 开辟 固定 大 小 的 缓冲 区 内 
存 ， 在 接收 上 游 服务 器 的 啊 应 时 如 果 绥 冲 区 已 满 则 暂停 接收 ， 等 待 缓冲 
区 中 的 啊 应 发 送 给 客户 端 后 缓冲 区 会 目 然 清空 ， 于 是 就 可 以 继续 接收 上 
游 服务 器 的 啊 应 了 。 这 种 设计 的 好 处 是 没有 使 用 大 量 内 存 ， 这 对 提高 ; 
发 连接 是 有 好 处 的 ， 同 时 也 没有 使 用 磁盘 文件 ， 这 对 降低 服务 需 负 载 、 
菏 些 情况 下 提高 请 求 处 理 能 力也 是 有 益 的 。 


























本 节 我 们 讨论 的 正 是 buffering 标 志 位 为 0 时 的 转发 啊 应 方式 ， 事 实 
上 ， 这 时 使 用 的 缓冲 区 也 是 接收 上 游 服 务 器 头 部 时 所 用 的 内 存 ， 其 大 小 
由 ngx_http_upstream_conf_t 配 置 结构 体 中 的 buffer_size 配 置 指定 。 


@ 注意 ”buffering 标 志 位 的 值 其 实 可 以 根据 上 游 服务 器 的 响应 头 


部 而 改变 。 在 12.1.3 节 中 我 们 介绍 过 change_buffering 标 志 位 ， 当 它 的 值 为 


1 时 ， 如 果 process_header 方 法 解析 出 X-Accel-Buffering 头 部 并 设置 到 
headers_in 结 构 体 中 后 ， 将 根据 该 头 部 的 值 改 变 buffeting 标 志 位 。 当 又 - 
Accel-Buffering 头 部 值 为 es 时， 对 于 本 次 请 求 而 言 ，buffering 相 当 于 重 设 
为 1， 如 果 头 部 值 为 no， 则 相当 于 buffering 改 为 0， 除 此 以 外 的 头 部 值 将 
不 产生 作用 (参见 ngx_http_upstream_process_buffering 方 法 ) 。 因 此 ， 转 
发 响应 时 究竟 是 否 需要 打开 缓存 ， 可 以 在 运行 时 根据 请 求 的 不 同 而 灵活 
变换 。 


12.7.1 转发 啊 应 的 包头 


转发 响应 包头 这 一 动作 是 在 ngx_http_upstream_send_response 方 法 中 
完成 的 ， 无 论 buffering 标 志 位 是 否 为 0， 都 会 使 用 该 方法 来 发 送 响应 的 
包头 ， 图 12-7 和 图 12-9 共 同 构成 了 ngx_http_upstream_send_response 方 法 
的 完整 流程 。 先 来 看 一 下 图 12-7， 它 描述 了 单一 缓冲 区 下 是 如 何 转发 包 
头 到 客户 端 ， 以 及 为 转发 包 体 做 准备 的 。 





因为 转发 啊 应 包头 这 一 过 程 并 不 存在 反复 调用 的 问题 ， 所 以 图 12-7 
中 主要 完成 了 两 项 工作 : 将 12.5 节 中 解析 出 的 包头 发 送 给 下 游 的 客户 
端 、 设 置 转发 包 体 的 处 理 方法 。 下 面 详细 解释 图 12-7 描 述 的 11 个 步骤。 


1) 调用 ngx_http_send_header 方 法 回 下 游 的 客户 端 发 送 HTTP 包 头 。 
在 接收 上 游 服 务 器 的 啊 应 包头 时 ， 在 图 12-5 的 第 6 步 中 ，HTTP 模 块 会 通 


过 process_header 方 法 解析 包头 ， 并 将 解析 出 的 值 设置 到 
ngx_http_upstream_t 结 构 体 的 headers_in 成 员 中 ， 而 在 第 8 步 中 ， 
ngx_http_upstream_process_headers 方 法 则 会 把 headers_in 中 的 头 部 设置 到 
将 要 发 送 给 客户 端的 headers_out 结 构 体 中 ，ngx_http_send_header 方 法 就 
是 用 来 把 这 些 包 头发 送 给 客户 端的 。 这 一 步 同 时 会 将 header_sent 标 志 位 
置 为 1 (header_sent 标 志 位 在 12.4 节 中 发 送 请 求 到 上 游 服 务 器 时 会 使 

用 ) 。 













1) 调用 ngx_http_send_header 
方法 向 客户 端 发 送 HTTP 包 头 
[检查 来 自 客 户 端的 HTTP 请 求 包 体 ] 








[客户 端 请 求 的 包 体 保存 在 了 临时 文件 中 ] 









[客户 端 


) ngx_pool_run_cleanup_file i 的 请 求 没 有 包 体 
2 ) 调 用 ngx_pooL_run_cleanup_fil 或 者 包 体 没有 保存 在 临时 文件 中 ] 


方法 清理 存放 请 求 包 体 的 文件 
[HTTP 模 块 是 否 实 现 input_filter 方 法 ] 











[已 经 实现 了 input_filter 方 法 ] 


[HTTP 模块 没有 实现 input_filter 方 法 ] 







3 ) 用 upstream 
提供 的 默认 方法 设置 input_filter 














4) 设 置 读 事件 处 理 方法 


read_event handler 











5) 设 置 写 事件 处 理 方法 


write _ event_handler 








6 ) 调 用 input_filter_init 方法 
[检查 缓冲 区 中 是 否 已 经 接收 到 包 体 ] 
[缓冲 区 中 已 经 含有 包 体 ] 






[缓冲 区 中 没有 接收 到 包 体 ] 












7) 调 用 input _filter 
方法 处 理 本 次 接收 到 的 响应 包 体 












8) 调用 ngx_ht tp_upstream_process_non_ 
buffered_downstream 方 》 










10) 调 用 ngx_http_send _special 
方法 





服务 器 的 套 接 字 ] 
[ 套 接 字 上 






[检测 与 上 游 
没有 可 读 内 容 ] 










[ 套 接 字 上 有 可 读 内 容 ] 





11) 调用 ngx_http_upstream_process_non_ 
buffered_upstream 方 法 





图 12-7 buffetring 标 志 位 为 0 时 发 送 响应 包头 的 流程 


2) 如 果 客 户 端的 请 求 中 有 HTTP 包 体 ， 而 且 曾 经 调用 过 11.8.1 节 中 
的 ngx_http_read_client_request_body 方 法 接收 HTTP 包 体 并 把 包 体 存放 在 
了 临时 文件 中 ， 这 时 就 会 调用 ngx_pool_run_cleanup_file 方 法 清理 临时 文 
件 。 为 什么 要 在 这 一 步 清理 临时 文件 呢 ? 因为 上 游 服务 器 发 送 响应 时 可 
能 会 使 用 到 临时 文件 ， 之 后 收 到 响应 解析 响应 包头 时 也 不 可 以 清理 临时 
文件 ， 而 一 旦 开始 向 下 游客 户 端 转发 HTTP 响 应 时 ， 则 意味 着 肯定 不 会 
再 需要 客户 端 请求 的 包 体 了 ， 这 时 可 以 关闭 、 转 移 或 者 删除 临时 文件 ， 
具体 动作 由 HTTP 模 块 实现 的 hander 回 调 方 法 决定 。 

















3) 如 果 HTTP 模 块 没有 实现 过 滤 包 体 的 input_filter 方 法 ， 则 再 把 
12.6.2 节 介绍 过 的 默认 的 ngx_http_upstream_non_buffered_filter 方 法 作为 
处 理 包 体 的 方法 ， 它 的 工作 就 在 于 使 用 out_bufs 链 表 指 向 接收 到 的 buffer 
绥 冲 区 内 容 。 在 12.7.2 市 中 将 会 综合 介绍 它 的 作用 。 








4) 设置 读 取 上 游 服 务 费 响应 的 方法 为 
ngx_http_upstream_process_non_buffered_upstream， 即 设置 upstream 中 的 
read_event_handler 回 调 方 法 ， 这 样 ， 当 上 游 服 务 器 接收 到 啊 应 时 ， 通 过 
ngx_http_upstream_handler 方 法 可 最 终 调用 


ngx_http_upstream_process_non_buffered_upstream 来 接收 啊 应 。 


5) 将 ngx_http_upstream_process_non_buffered_downstream 设 置 为 癌 
下 游客 户 端 发 送 包 体 的 方法 ， 也 就 是 把 请 求 ngx_http_request_t 中 的 
write_event_handler 设 置 为 这 个 方法 ， 这 样 ， 一 旦 TCP 连 接 上 可 以 癌 下 游 


客户 端 发 送 数据 时 ， 会 通过 ngx_http_handler 方 法 最 终 调用 到 
ngX_http_upstream_process_non_buffered_downstream 来 发 送 啊 应 包 体 。 


6) 调用 HTTP 模 块 实现 的 input_filter_init 方 法 〈 当 HTTP 模 块 没 有 实 
现 input_filter 方 法 时 ， 它 是 默认 任何 事情 也 不 做 的 
ngx_http_upstream_non_buffered_filter_init 方 法 ) ， 为 input_filter 方 法 处 
理 包 体 做 初始 化 准备 。 








检测 buffer 绥 冲 区 在 解析 完 包 头 后 ， 是 否 还 有 已 经 接收 到 的 包 体 
(实际 上 就 是 检查 buffer 组 冲 区 中 的 last 指 针 是 否 等 于 pos 指 针 ) 。 如 果 
已 经 接收 到 包 体 ， 则 跳 到 第 7 步 执 行 ， 如 果 没 有 接收 到 包 体 ， 则 跳 到 第 9 


步 执行 。 
7) 调用 input_filter 方 法 处 理 包 体 。 


8) 调用 ngx_http_upstream_process_non_buffered_downstream 方 法 把 
本 次 接收 到 的 包 体 问 下 游客 户 端 发 送 。 





9) 将 buffer 缓 冲 区 清空 ， 其 实 就 是 执行 下 面 两 行 语句 : 





U->buffer .pos = u->buffer.start; 
U->buffer .last = u->buffer.start,; 





pos 指 针 一 般 指 向 未 经 处 理 的 啊 应 ， 而 last 指 针 一 般 指 癌 刚 接收 到 的 
啊 应 ， 这 时 把 它们 全 部 设 为 指 问 缓冲 区 起 始 地 址 的 start 指 针 ， 即 表示 清 


空 缓冲 区 。 


10) 调用 ngx_http_send_special 方 法 ， 如 下 所 示 。 





If (ngx_http_send_ special(r, NGX_HTTP_FLUSH) == NGX_ ERROR) { 
ngx_http_upstream finalize_request(r, u, 0); 
return; 


} 





NGX_HTTP_FLUSH 标 志 位 意味 着 如 果 请 求 rz 的 out 绥 冲 区 中 依然 有 
等 待 发 送 的 响应 ， 则 “催促 ”着 发 送出 它们 。 








11) 如 果 与 上 游 服 务 器 的 连接 上 有 可 读 事 件 ， 则 调用 
ngx_http_upstream_process_non_buffered_upstream 方 法 处 理 啊 应 ; 个 
则 ， 当 前 流程 结束 ， 将 控制 权 交 还 给 Nginx 框 架 。 


以 上 步骤 提 到 的 下 游 处 理 方法 
ngx_http_upstream_process_non_buffered_downstream 和 上 游 处 理 方 法 
ngx_http_upstream_process_non_buffered_upstream 都 将 在 下 文中 介绍 


12.7.2 ”转发 啊 应 的 包 体 


当 接 收 到 上 游 服 务 器 的 响应 时 ， 将 会 由 
ngx_http_upstream_process_non_buffered_upstream 方 法 处 理 连接 上 的 这 
个 读 事件 ， 该 方法 比较 简单 ， 下 面 直接 列举 源 代 码 说 明 其 流程 。 





static void ngx_http_upstream process_non_buffered_upstream(ngx_http_request t *r, r 


ngx_connection t *c; 
// 获取 


Nginx 与 上 游 服务 器 间 的 


TCP 连 接 


c = u->peer.connection; 
// 如 果 读 取 响 应 超时 (超时 时 间 为 


read_timeout) ， 则 需要 结束 请 求 


if (c->read->timedout) { 
// ngx_http_upstream_finalize_request 方 法 可 参见 


12.9.3 节 


ngx_http_upstream finalize_request(r, u, 0); 
return; 


} 
/这 个 方法 才 是 真正 决定 以 固定 内 存 块 作为 缓存 时 如 何 转发 响应 的 ， 注 意 ， 传 递 的 第 


2 个 参数 是 


oO*/ 


} 


ngx_http_upstream process_ non_buffered request(r, 0); 





可 以 看 到 ， 实 际 接收 上 游 服 务 器 啊 应 的 其 实 是 
ngx_http_upstream_process_non_buffered_request 方 法 ， 先 不 着 急 看 它 的 
实现 ， 先 来 看 看 同 下 游客 户 端 发 送 响 应 时 调用 的 
ngx_http_upstream_process_non_buffered_downstream 方 法 是 怎样 实现 


的 ， 如 下 所 示 。 








static void ngx_http_upstream process_ non_buffered downstream(ngx_http_request t *r. 


{ 


ngx_event_t *wev; 
ngx_connection _t *c; 
ngx_http_upstream t *u; 
// 注意 ， 这 个 


Nginx 与 客户 端 之 间 的 

TCP 连 接 
Cc = r->connection,; 
U = r->upstream; 


wev = c->write; 
/* 如 果 发 送 超时 ， 那 么 同样 要 结束 请 求 ， 超 时 时 间 就 是 


nginx.conf 文 件 中 的 
Send_ timeout 配 置 项 


*/ 
if (wev->timedout) { 
c->timedout = 1; 
// 注意 ， 结 束 请 求 时 传递 的 参数 是 


NGX_HTTP_REQUEST_TIME_OUT 
ngx_http_upstream finalize_request(r, u, NGX_HTTP_REQUEST_TIME_OUT); 
return; 


} 
// 同样 调用 该 方法 向 客户 端 发 送 响应 包 体 ， 注 意 ， 传 递 的 第 


2 个 参数 是 


ngx_http_upstream process non_buffered request(r, 1); 





无 论 是 接收 上 游 服 务 器 的 响应 ， 还 是 向 下 游客 户 端 发 送 响应 ， 最 终 
调用 的 方法 都 是 ngx_http_upstream_process_non_buffered_request， 唯 一 
的 区 别 是 该 方法 的 第 2 个 参数 不 同 ， 当 需要 读 取 上 游 的 啊 应 时 传递 的 是 
0， 当 需要 同 下 游 发 送 啊 应 时 传递 的 是 1。 下 面 移 看 看 该 方法 到 撒 做 了 哪 


些 事情 ， 如 图 12-8 所 示 。 


图 12-8 中 的 do_write 变 量 就 是 
ngx_http_upstream_process_non_buffered_request 方 法 中 的 第 2 个 参数 ， 当 
然 ， 首 先 它 还 会 有 一 个 初始 化 ， 如 下 所 示 。 











do_write = do_write || u->length == 0， 














这 里 的 length 变 量 表示 还 需要 接收 的 上 游 包 体 的 长 度 ， 当 length 为 0 
时 ， 说 明 不 再 需要 接收 上 游 的 啊 应 ， 那 只 能 继续 癌 下 游 发 送 啊 应 ， 
此 ，do_write 只 能 为 1]。do_write 标 志 位 表示 本 次 是 否 癌 下 游 发 送 啊 应 。 


下 面 详细 解释 图 12-8 中 的 每 个 步骤 。 


1) 如 果 do_write 标 志 位 为 1， 则 跳 到 第 2 步 开 始 向 下 游 发 送 啊 应 ; 如 
果 do_write 为 0， 则 表示 需要 由 上 游 读 取 啊 应 ， 这 时 跳 到 第 6 步 执 行 。 注 
意 ， 在 图 12-8 中 ， 这 一 步 是 在 一 个 大 循环 中 执行 的 ， 也 就 是 说 ， 与 上 、 
下 游 间 的 通信 可 能 反复 执行 。 














2) 自 先 检查 缓存 中 来 自 上 游 的 啊 应 包 体 ， 是 人 否 还 有 未 转发 给 下 游 
的 。 这 个 检查 过 程 很 简单 ， 因 为 每 当 在 缓冲 区 中 接收 到 上 游 的 啊 应 时 ， 
都 会 调用 input_filter 方 法 来 处 理 。 当 HTTP 模 块 没 有 实现 该 方法 时 ， 我 们 
就 会 使 用 12.6.2 节 介绍 过 的 ngx_http_upstream_non_buffered_filter 方 法 来 
处 理 啊 应 ， 访 方法 会 在 out_bufs 链 表 中 增加 ngx_buf _t 绥 冲 区 (没有 分 配 





实际 的 内 存 ) 指 辐 buffer 中 接收 到 的 啊 应 。 因 此 ， 在 同 下 游 发 送 包 体 
时 ， 直 接 发 送 out_bufs 绥 冲 区 指 疝 的 内 容 即 可 ， 每 当 发 送 成 功 时 则 会 在 
下 面 的 第 4 步 中 更 新 out_bufs 绥 冲 区 ， 从 而 将 已 经 发 送出 去 的 ngx_buf t 成 
员 回 收 到 free_bufs 链 表 中 。 








事实 上 ， 检 醋 是 否 有 内 容 需 要 转 及 给 下 游 的 代码 是 这 样 的 : 








If (u->out_bufs || u->busy_bufs) { … 


} 





可 能 有 人 会 奇怪 ， 为 什么 除了 out_bufs 绥 冲 区 链表 以 外 还 要 检查 
busy_bufs 呢 ?这 是 因为 在 第 3 步 同 下 游 发 送 out_bufs 指 同 的 响应 时 ， 未 必 
可 以 一 次 发 送 完 。 这 时 ， 在 第 4 步 中 ， 会 使 用 busy_bufs 指 问 out_bufs 中 的 
内 容 ， 同 时 将 out_bufs 置 为 空 ， 使 得 它 在 继续 处 理 接收 到 的 响应 包 体 的 
ngx_http_upstream_non_buffered_filter 方 法 中 指向 新 收 到 的 响应 。 因 此 ， 
只 有 out_bufs 和 busy_bufs 链 表 都 为 空 时 ， 才 表示 没有 响应 需要 转发 到 下 
游 ， 这 时 路 到 第 5 步 执行 ， 否 则 跳 到 第 2 步 向 下 游 发 送 响应 。 





3) 调用 ngx_http_output_filter 方 法 疝 下 游 发 送 out_bufs 指 问 的 内 容 ， 
其 代码 如 下 。 





rc = ngx_http_output_filter(r, u->out_bufs); 













2) 检 测 发 送 缓冲 区 
中 是 否 有 内 容 


[检查 outbufs 或 者 busy_bufs 链表 是 否 为 空 ] 






















1 ) 结合 length 成 员 和 do_write 


重 置 do_write 


合 1 
参 





tbufs 或 者 busy_bufs 不 为 空 
[检测 do write 标志 位 ] [domite 标 志 位 为 a yufs 或 者 busy_bufs 不 为 空 ] 
[两 链表 丝 指 向 NULL] 


3 ) 调 用 ngx_http_output_filter 
方法 发 送 包 体 











4) 调 用 ngx_chain_update_chains 


do_write 慰 志 位 为 0 
A 方法 更 新 缓 种 区 链表 













S) 更 新 buffer 
缓冲 区 中 的 pos、 last 


6) 检测 buffer 
缓冲 区 的 空闲 空间 长 度 
[检查 空闲 空间 长 度 是 否 为 0, 以 及 读 事 件 的 ready 标 志 位 ] 


[buffer 还 有 空闲 空间 , 且 ready 标志 位 为 1] 


7) 调 用 recv 
方法 接收 响应 
[检测 recv 返 回 值 ] 








[buffer 绥 冲 区 用 尽 , 或 ready 为 0] 






[ 读 取 到 叫 应 包 体 ] [未 读 取 到 响应 包 体 ] 
方法 处 理 包 末 


9) 设 置 do write 
标志 位 1 


[返回 NGX_AGAIN] 











i 
11) 将 下 游 写 事件 添加 到 
定时 器 中 


人 添加 到 


13) 将 上 游 读 事件 添加 到 
定时 右 中 


图 12-8 ngx_http_upstream_process_non_buffered_request 方 法 的 流程 图 


读者 在 这 里 可 能 会 有 疑问 ， 在 busy_bufs 不 为 空 时 ， 不 是 也 有 内 容 要 
发 送 吗 ? 注意 ，busy_bufs 指 癌 的 是 上 一 次 ngx_http_output_filter 示 发送 完 
的 缓存 ， 这 时 请 求 ngx_http_request_t 结 构 体 中 的 out 绥 冲 区 已 经 保存 了 它 
的 内 容 ， 不 需要 再 次 发 送 busy_bufs 了 。 








4) 调用 ngx_chain_update_chains 方 法 更 新 上 文 说 过 的 free_bufs、 
busy_bufs、out_bufs 这 3 个 绥 冲 区 链表 ， 它 们 实际 上 做 了 以 下 3 件 事 情 。 





. 清空 out_bufs 链 表 。 


. 把 out_bufs 中 已 经 发 送 完 的 ngx_buf_t 结 构 体 清空 重 置 ( 即 把 pos 和 
last 成 员 指 向 statt) ， 同 时 把 它们 追加 到 free_bufs 链 表 中 。 


如 果 out_bufs 中 还 有 未 发 送 完 的 ngx_buf_t 结 构 体 ， 那 么 添加 到 
busy_bufs 链 表 中 。 这 一 步 与 ngx_http_upstream_non_buffered_filtet 方 法 的 


执行 是 对 应 的 。 





5) 当 busy_bufs 链 表 为 空 时 ， 表 示 到 目前 为 止 需要 向 下 游 转 发 的 响 
应 包 体 都 已 经 全 部 发 送 完 了 也 就 是 说 ，ngx_http_request_t 结 构 体 中 的 
out 缓 冲 区 都 发 送 完了 ) ， 这 时 将 把 buffer 接 收 缓冲 区 清空 (pos 和 1]ast 成 
员 指 向 start) ， 这 样 ，buffer 接 收 缓冲 区 中 的 内 容 释 放 后 ， 才 能 继续 接收 
更 多 的 响应 包 体 。 


6) 获取 buffer 组 冲 区 中 还 有 多 少 剩 余 空间 ， 即 : 





size = U->buffer.end - U->buffer ,Last 


这 里 获取 的 size 就 是 第 7 步 recv 方 法 能 够 接收 的 最 大 字 节 数 。 


当 size 大 于 0， 且 与 上 游 的 连接 上 确实 有 可 读 事 件 时 检查 读 事 件 的 
ready 标 志 位 ) ， 就 会 跳 到 第 7 步 开始 接收 啊 应 ， 人 否则 直接 路 到 10 步 准备 
结束 本 次 调度 中 的 转发 动作 。 


7) 调用 recv 方 法 将 上 游 的 啊 应 接收 到 buffer 绥 冲 区 中 。 检 查 recv 的 
返回 值 ， 如 果 返 回 正 数 ， 则 表示 确实 接收 到 啊 应 ， 跳 到 第 8 步 处 理 接 收 
到 的 包 体 ， 如 果 返 回 NGX_AGAIN， 则 表示 期 待 epoll 下 次 有 读 事 件 时 再 
继续 调度 ， 这 时 跳 到 第 10 步 执行 ， 如 果 返 回 0， 则 表示 上 游 服务 器 关闭 
了 连接 ， 跳 到 第 9 步 执行 。 





8) 调用 input_filter 方 法 处 理 包 体 〈( 参 考 12.6.2 市 的 默认 处 理 方 
| 去) 


9) 执行 到 这 一 步 表 示 读 取 到 了 来 目 上 游 的 啊 应 ， 这 时 设置 do_write 
标志 位 为 1， 同 时 跳 到 第 1 步 准备 问 下 游 转 及 刚 收 到 的 啊 应 。 


10) 调用 ngx_handle_write_event 方 法 将 Nginx 与 下 游 之 间 连 接 上 的 
写 事件 添加 到 epoll 中 。 


11〉 调 用 ngx_add_timer 方 法 将 Nginx 与 下 游 之 间 连 接 上 的 写 事件 添 
加 到 定时 器 中 ， 超 时 时 间 就 是 配置 文件 中 的 send_timeout 配 置 项 。 


12) 调用 ngx_handle_read_event 方 法 将 Nginx 与 上 游 服 务 器 之 间 的 连 
接 上 的 读 事件 添加 到 epol 中 。 


13) 调用 ngx_add_timer 方 法 将 Nginx 与 上 游 服 务 器 之 间 连 接 上 的 读 
事件 添加 到 定时 堪 中 ， 超 时 时 间 束 是 ngx_http_upstream_conf t 配 置 结构 
体 中 的 read_timeonut 成 员 。 





阅读 完 第 11 章 ， 读 者 应 该 很 熟悉 Nginx 读 / 写 事件 的 处 理 过 程 了 。 另 
外 ， 理 解 转发 包 体 这 一 过 程 最 关键 的 是 弄 清楚 缓冲 区 的 用 法 ， 特 别 是 分 
配 了 实际 内 存 的 buffer 绥 冲 区 与 仅仅 负 贡 指向 buffer 绥 冲 区 内 容 的 3 个 链 
表 (out_bufs、busy_bufs、free_bufs) 之 间 的 关系 ， 这 样 就 对 这 种 转发 
过 程 的 优 缺 点 非常 清楚 了 。 如 果 下 游 网 速 慢 ， 那 么 有 限 的 buffer 缓 冲 区 
束 会 降低 上 游 的 发 送 啊 应 速度 ， 可 能 对 上 游 服 务 器 市 来 高 并 发 压力 。 














12.8 ”以 上 游 网 速 优先 来 转发 啊 应 





如 果 上 游 服务 器 向 Nginx 发 送 响应 的 速度 远 快 于 下 游客 户 端 接收 
Nginx 转 发 响应 时 的 速度 ， 这 时 可 以 通过 将 ngx_http_upstream_conf_{t 配 
置 结 构 体 中 的 buffering 标 志 位 设 为 1， 人 允许 upstream 机 制 打开 更 大 的 缓冲 
区 来 缓存 那些 来 不 及 向 下 游 转 发 的 响应 ， 人 允许 当 达 到 内 存 构成 的 缓冲 区 
上 限时 以 磁盘 文件 的 形式 来 缓存 来 不 及 向 下 游 转发 的 响应 。 什 么 是 更 大 
的 缓冲 区 呢 ? 由 12.7 节 我 们 知道 ， 当 buffering 标 志 位 为 0 时 ， 将 使 用 
ngx_http_upstream_conf t 配 置 结 构 体 中 的 buffer_size 指 定 的 一 块 固 定 大 
小 的 缓冲 区 来 转发 响应 ， 而 当 buffering 为 1 时 ， 则 使 用 bufs 成 员 指定 的 内 
存 缓冲 区 《最 多 拥有 bufs.num 个 ， 每 个 缓冲 区 大 小 固定 为 bufs.size 字 
节 ) 来 转发 响应 ， 当 上 游 响应 占 满 所 有 缓冲 区 时 ， 使 用 最 大 不 超过 


max_temp_file_size 字 节 的 临时 文件 来 缓存 啊 应 。 








事实 上 ， 官 方 发 布 的 ngx_http_proxy_module 反 向 代理 模块 默认 配置 
下 惑 是 使 用 这 种 方式 来 转发 上 游 服务 器 啊 应 的 ， 由 于 它 涉及 了 多 个 内 存 
缓冲 区 的 配合 问题 ， 以 及 临时 磁盘 文件 的 使 用 ， 导 致 它 的 实现 方式 异 第 
复杂 ，12.8.1 节 介绍 的 ngx_event_pipe_t 结 构 体 是 该 转发 方式 的 核心 结构 
体 ， 需 要 基于 它 来 理解 转发 流程 。 














这 种 转发 啊 应 方式 集成 了 Nginx 的 文件 缓存 功能 ， 本 市 将 只 讨论 纯 


粹 转发 响应 的 流程 ， 不 会 涉及 文件 缓存 部 分 (以 临时 文件 缓存 响应 并 不 
属于 文件 缓存 ， 因 为 临时 文件 在 请 求 结束 后 会 被 删除 ) 。 








12.8.1 ngx_event_pipe_t 结 构 体 的 意义 


如 果 将 ngx_http_upstream_conf {配置 结构 体 的 buffering 标 志 位 设置 
为 1， 那 么 ngx_event_pipe_t 结 构 体 必须 要 由 HTTP 模 块 创建 。 


@ 注意 upstream 中 的 pipe 成 员 默 认 指 向 NUIL 空 指针 ， 而且 
upstteam 机 制 永远 不 会 为 它 自动 实例 化 ， 因 此 ， 必 须 由 使 用 upstteam 的 
HTTP 模 块 为 pipe 分 配 内 存 。 





ngx_event_pipe_t 结 构 体 维护 着 上 下 游 间 转发 的 响应 包 体 ， 它 相当 复 
杂 。 例 如 ， 缓 冲 区 链表 ngx_chain_t 类 型 的 成 员 就 定义 了 6 个 (包括 
free_raw_bufs、in、out、free、busy、Ppreread_bufs) ， 为 什么 要 用 如 此 
复杂 的 数据 结构 支撑 看 似 简 单 的 转发 过 程 呢 ? 这 是 因为 Nginx 的 宗旨 就 
是 高 效率 ， 所 以 它 绝 不 会 把 相同 内 容 复 制 到 两 块 内 存 中 ， 而 同一 块 内 存 
如 果 既 要 用 于 接收 上 游 发 来 的 响应 ， 又 要 准备 向 下 游 发 送 ， 很 可 能 还 要 
准备 写 入 临时 文件 中 ， 这 就 带 来 了 很 高 的 复杂 度 ，ngx_event_pipe_t 结 构 
体 的 任务 就 在 于 解决 这 个 问题 。 




















理解 这 个 结构 体 中 各 个 成 员 的 含义 将 会 帮助 我 们 弄 清楚 buffering 为 
1 时 转发 啊 应 的 流程 ， 特 别 是 可 以 弄 清楚 Nginx 绝 不 复制 重复 内 存 的 高 效 


做 法 是 如 何 实现 的 。 当 然 ， 我 们 也 可 以 先 跳 到 12.8.2 节 综合 理解 这 种 转 
发 方式 下 的 运行 机 制 ， 再 针对 流程 中 遇 到 的 ngx_event_pipe_{t 结 构 体 中 的 
成 员 返 回 到 本 节 来 查询 其 意义 。 下 面 看 一 下 它 各 个 成 员 的 意义 。 











typedef struct ngx_event_pipe_ s ngx_event pipe_t; 
// 处 理 接收 自 上 游 的 包 体 的 回调 方法 原型 





typedef ngx_int t (*ngx_event_pipe_input_filter_pt) (ngx_event_pipe_t *p, ngx_buf_t 
// 向 下 游 发 送 响 应 的 回调 方法 原型 


typedef ngx_int_t (*ngx_event_ pipe_ output_ filter_pt)(void *data, ngx_chain t *chain, 
struct ngx_event_pipe_s { 
// Nginx 与 上 游 服务 器 间 的 连接 





ngx_connection_t *upstream; 
// Nginx 与 下 游客 户 端 间 的 连接 


ngx_connection_t *downstream,; 
/* 直 接 接收 自 上 游 服 务 器 的 缓冲 区 链表 ， 注 意 ， 这 个 链表 中 的 顺序 是 逆序 的 ， 也 就 是 说 ， 链 表 前 端的 


ngx_buf_t 缓 冲 区 指向 的 是 后 接收 到 的 响应 ， 而 后 端的 


ngx_buf_t 缓 冲 区 指向 的 是 先 接 收 到 的 响应 。 因 此 ， 


free_raw_bufs 链 表 仅 在 接收 响应 时 使 用 


* 
ngx_chain_t *free_raw_bufs; 
/* 表 示 接 收 到 的 上 游 响 应 缓冲 区 。 通 常 ， 


in 链表 是 在 


input_filter 方 法 中 设置 的 ， 可 参考 


ngx_event_pipe_copy_input_filter 方 法 ， 它 会 将 接收 到 的 缓冲 区 设置 到 





in 链 表 中 


*/ 
ngx_chain _t *in; 
// 指向 刚刚 接收 到 的 一 个 缓冲 区 


ngx_chain t **Jast_in， 
/* 保 存 着 将 要 发 送 给 客户 端的 缓冲 区 链表 。 在 写 入 临时 文件 成 功 时 ， 会 把 


in 链表 中 写 入 文件 的 缓冲 区 添加 到 


Out 链表 中 


*/ 
ngx_chain _t *out; 
// 指向 刚 加 入 


Out 链表 的 缓冲 区 ， 暂 无 实际 意义 


ngx_chain t **]last_out,; 
// 等 待 释放 的 缓冲 区 


ngx_chain_t *free 
/* 设 置 


busy 缓 冲 区 中 待 发 送 的 响应 长 度 触 发 值 ， 当 达到 


busy_size 长 度 时 ， 必 须 等 待 


busy 绥 冲 区 发 送 了 足够 的 内 容 ， 才 能 继续 发 送 


OUt 和 


in 缓冲 区 中 的 内 容 


yA 
ssize_t busy_size; 
/* 表 示 上 次 调用 


ngx_http_output_filter 方 法 发 送 响应 时 没有 发 送 完 的 缓冲 区 链表 。 这 个 链表 中 的 缓冲 区 已 经 保存 到 请 求 的 


Out 链表 中 ， 


busy 仅 用 于 记录 还 有 多 大 的 响应 正 等 待 发 送 


4 
ngx_chain_t *busy; 
/* 处 理 接收 到 的 来 自 上 游 服 务 器 的 缓冲 区 。 一 般 使 用 


Upstream 机 制 默 认 提 供 的 





ngx_event_pipe_copy_input_filter 方 法 作为 


input_filter*/ 
ngx_event_pipe_input_filter_pt input_ filter; 
/用 于 





input_filter 方 法 的 成 员 ， 一 般 将 它 设置 为 


ngx_http_request 七 结构 体 的 地 址 


WA 
void *input_ctx; 
/* 表 示 向 下 游 发 送 响 应 的 方法 ， 默 认 使 用 


ngx_http_output_filter 方 法 作为 


output_filter*/ 
ngx_event_pipe_output_filter_pt output_filter; 
// 指向 





ngx_http_request 七 结构 体 


void *output_ctx; 
// 标志 位 ， 


read 为 


1 时 表示 当前 已 经 读 取 到 上 游 的 响应 


unsigned read:1; 
/* 标 志 位 ， 为 


1 时 表示 启用 文件 缓存 。 本 章 描述 的 场景 都 忽略 了 文件 缓存 ， 也 就 是 默认 


cacheable 值 为 


0*/ 
unsigned cacheable:1; 
// 标志 位 ， 为 


1 时 表示 接收 上 游 响应 时 一 次 只 能 接收 一 个 


ngx_buf 七 缓冲 区 


unsigned single_buf:1; 
/* 标 志 位 ， 为 


1 时 一 旦 不 再 接收 上 游 响应 包 体 ， 将 尽 可 能 地 立刻 释放 缓冲 区 。 所 谓 尽 可 能 是 指 ， 


po01 内 存 池 


* 
/ 
unsigned free_bufs:1; 
/* 提 供给 


HTTP 模 块 在 


input_filter 方 法 中 使 用 的 标志 位 ， 表 示 


Nginx 与 上 游 间 的 交互 已 结束 。 如 果 


HTTP 模 块 在 解析 包 体 时 ， 认 为 从 业务 上 需要 结束 与 上 游 间 的 连接 ， 那么 可 以 把 


upstream_done 标 志 位 置 为 


1*/ 
unsigned upstream done:1,; 
/*Nginx 与 上 游 服务 器 之 间 的 连接 出 现 错误 时 ， 


Upstream_error 标 志 位 为 


1， 一 般 当 接收 上 游 响 应 超时 ， 或 者 调用 


TeCV 接 收 出 现 错误 时 ， 就 会 把 该 标志 位 置 为 


1*/ 
unsigned upstream error:1; 
/* 表 示 与 上 游 的 连接 状态 。 当 


一 旦 这 个 缓冲 区 没有 被 引用 ， 如 ; 


Nginx 与 上 游 的 连接 已 经 关闭 时 ， 


Upstream_eof 标 志 位 为 


1*/ 
unsigned upstream eof:1; 
/* 表 示 暂 时 阻塞 住 读 取 上 游 响 应 的 流程 ， 期 待 通过 向 下 游 发 送 响应 来 清理 出 空闲 的 缓冲 区 ， 再 用 空 出 的 缓冲 [ 


upstream_blocked 标 志 位 为 


1 时 会 在 


ngx_event_pipe 方 法 的 循环 中 先 调用 


ngx_event_pipe_write_to_downstream 方 法 发 送 响应 ， 然 后 再 次 调用 








ngx_event_pipe_read_upstream 方 法 读 取 上 游 响 应 


unsigned upstream blocked:1; 
// downstream_done 标 志 位 为 


1 时 表示 与 下 游 间 的 交互 已 经 结束 ， 目 前 无 意义 


unsigned downstream done:1; 
/*Nginx 与 下 游客 户 端 间 的 连接 出 现 错误 时 ， 


downstream_error 标志 位 为 


1。 在 代码 中 ， 一 般 是 向 下 游 发 送 响 应 超时 ， 或 者 使 用 


ngx_http_output_filter 方 法 发 送 响应 却 返回 


NGX_ERROR 时 ， 把 


downstream_error 标志 位 设 为 


1*/ 
unsigned downstream error:1; 
/* cyclic_temp_file 标 志 位 为 


1 时 会 试图 复 用 临时 文件 中 曾经 使 用 过 的 空间 。 不 建议 将 


cyclic_temp_file 设 为 


1。 它 是 由 


ngx_http_upstream_conf_t 配 置 结构 体 中 的 同名 成 员 赋 值 的 


* 
/ 
unsigned cyclic temp_file:1; 
// 表示 已 经 分 配 的 缓冲 区 数目 ， 
allocated 受 到 


bufs .num 成 员 的 限制 


ngx_int_t allocated; 
/*bufSs 记 录 了 接收 上 游 响应 的 内 存 缓冲 区 大 小 ， 其 中 


bufs ,Size 表示 每 个 内 存 缓 冲 区 的 大 小 ， 而 


bufs ,num 表 示 最 多 可 以 有 


num 个 接收 缓冲 区 


*/ 
ngx_bufs_t bufs,; 
// 用 于 设置 、 比 较 缓冲 区 链表 中 


ngx_buf 七 结构 体 的 


tag 标 志 位 


ngx_buf_tag_t tag; 
// 已 经 接收 到 的 上 游 响应 包 体 长 度 


off t read_length ; 
全 与 


ngx_http_upstream_conf_t 配 置 结构 体 中 的 


max_temp_file_size 含 义 相 同 ， 同 时 它们 的 值 也 是 相等 的 ， 表 示 临 时 文件 的 最 大 长 度 


*/ 
off_t max_temp_file size; 
/ “与 





ngx_http_upstream_conf_t 配 置 结构 体 中 的 


temp_file_write_size 含 义 相 同 ， 同 时 它们 的 值 也 是 相等 的 ， 表 示 一 次 写 入 文件 时 的 最 大 长 度 





ssize_t temp_ file write size,; 
// 读 取 上 游 响应 的 超时 时 间 


ngx_msec_t read timeout; 
// 向 下 游 发 送 响应 的 超时 时 间 


ngx_msec_t send_timeout ; 
// 向 下 游 发 送 响应 时 ， 


TCP 连 接 中 设置 的 


send_lowat “水 位 ” 


ssize_t send_ lowat; 
// 用 于 分 配 内 存 缓冲 区 的 连接 池 对 象 


ngx_pool t *pool; 
// 用 于 记录 日 志 的 


ngx_1og 七 对 象 


ngx_log_t *1og ; 
// 表示 在 接收 上 游 服 务 器 响应 头 部 阶段 ， 已 经 读 取 到 的 响应 包 体 


ngx_chain t *preread_bufs 
// 表示 在 接收 上 游 服务 器 响应 头 部 阶段 ， 已 经 读 取 到 的 响应 包 体 长 度 


size_t preread_ size; 
// 仅 用 于 缓存 文件 的 场景 ， 本 章 不 涉及 ， 故 不 再 详 述 该 缓冲 区 


ngx_buf t *buf_to_file; 
// 存放 上 游 响应 的 临时 文件 ， 最 大 长 度 由 





max_temp_file_size 成 员 限 制 


ngx_temp_file t *temp_file; 
// 已 使 用 的 


ngx_buf t 缓 冲 区 数目 


int num， 


}; 








注意 ，ngx_event_pipe _t 结 构 体 仅 用 于 转发 响应 。 


12.8.2 ”转发 响应 的 包头 























开始 转发 响应 也 是 通过 ngx_http_upstream_send_response 方 法 执行 的 。 图 12-9 展 示 了 转发 | 


1 ) 调用 ngx_http_send_header 


方法 向 客户 端 发 送 HTTP 包 头 
[检查 来 自 客 户 端的 HTTP 请 求 包 体 ] 





| 和 容 吉明 请 求 没有 亿 体 
[客户 端 请 求 的 包 体 保 存在 了 临时 文件 中 ] 或 者 包 体 没 有 保存 在 临时 文件 中 ] 


2 ) 调 用 ngx_pool_ run_cleanup_file 
方法 清理 文件 


3 ) 初 始 化 ngx_event_pipe 
结构 体 





4 ) 初始 化 预 读 缓冲 
区 链表 


5) 设置 上 游 读 事件 处 理 方法 


read_event handler 


6 ) 设 置 下 游 写 事件 处 理 方法 


write_event handler 


7) 调 用 ngx_http_upstream_process_upstream 


方法 处 理 上 游 响 应 


© 





图 12-9 ”buffering 标 志 位 为 0 时 转发 响应 包头 的 流程 图 


下 面 说 明 一 下 图 12-9 中 的 步 又 





1) 首先 调用 ngx_http_send_header 方 法 向 下 游客 户 端 发 送 ngx_http_request_t 结 构 体 的 head 


2) 如 果 客 户 端 请 求 中 存在 HTTP 包 体 ， 而 且 包 体 已 经 保存 到 临时 文件 中 了 ， 这 时 将 会 调 


3) ngx_http_upstream _t 结 构 体 中 的 pipe 成 员 并 不 是 在 这 一 步 中 创建 ， 它 仅 在 这 一 步 中 初 ? 








// 注意 ， 这 里 是 直接 引用 必须 分 配 过 内 存 的 


pipe 指 针 


ngx_event_pipe_t* p = u->pipe; 


/* 设 置 向 下 游客 户 端 发 送 响 应 的 方法 为 
ngx_http_output_filter， 该 方法 在 第 
11 章 中 介绍 过 


Ry 
p->output_filter = (ngx_event_pipe_output_filter_pt) ngx_http_output_filter; 
/*output_ctx 指 向 当前 请 求 的 





ngx_http_request_t 结 构 体 ， 这 是 因为 接 下 来 转发 包 体 的 方法 都 只 接受 
ngx_event_pipe_t 参 数 ， 且 只 能 由 

output_ctx 成 员 获 取 到 表示 请 求 的 

ngx_http_request_t 结 构 体 

4 


p->output_ctx = r; 


// 设置 转发 响应 时 启用 的 每 个 缓冲 区 的 
tag 标 志 位 


p->tag = u->output.tag; 


// bufs 指 定 了 内 存 缓 冲 区 的 限制 


p->bufs = U->conf->bufs ; 
// 设置 


busy 缓 冲 区 中 待 发 送 的 响应 长 度 触发 值 


p->busy_size = u->conf->busy_buffers_size; 


// upstream 在 这 里 被 初始 化 为 


Nginx 与 上 游 服务 器 之 间 的 连接 


p->upstream = Uu->peer .connection; 


// downstream 在 这 里 被 初始 化 为 
Nginx 与 下 游客 户 端 之 间 的 连接 


p->downstream = c; 


// 初始 化 用 于 分 配 内 存 缓 冲 区 的 内 存 池 


p->pool = r->pool; 


// 初始 化 记录 日 志 的 
log 成 员 


p->1og = c->10g; 
// 设置 临时 存放 上 游 响应 的 单个 缓存 文件 的 最 大 长 度 


p->max_temp_file_size = u->conf->max_temp_file_size; 


// 设置 一 次 写 入 文件 时 写 入 的 最 大 长 度 


p->temp_file write_ size = u->conf->temp_file write size; 
// 以 当前 


location 下 的 配置 来 设置 读 取 上 游 响 应 的 超时 时 间 


p->read_timeout = u->conf->read timeout; 
// 以 当前 


location 下 的 配置 来 设置 发 送 到 下 游 的 超时 时 间 


p->send_timeout = clcf->send_timeout; 


// 设置 向 客户 端 发 送 响 应 时 
TcP 中 的 


send_lowat “水 位 ” 


p->send_lowat = clcf->send_ lowat; 








4) 初始 化 preread_bufs 预 读 缓 冲 区 链表 《所 谓 预 读 ， 就 是 在 读 取 包 头 时 也 预先 读 取 到 了 ; 





p->preread_bufs->buf = &u->buffer 
p->preread_bufs->next = NULL 
p->preread_size = u->buffer.last - U->buffer .pos 





实际 上 就 是 把 preread_bufs 中 的 缓冲 区 指向 存放 头 部 的 buffer 组 冲 区 ， 在 图 12-11 中 的 第 1 





5) 设置 处 理 上 游 读 事件 回调 方法 为 ngx_http_upstream_process_upstream。 





6) 设置 处 理 下 游 写 事件 的 回调 方法 为 ngx_http_upstream_process_downstream 。 





7) 调用 ngx_http_upstream_process_upstream 方 法 处 理 上 游 发 来 的 响应 包 体 。 





ngx_event_pipe_t 结 构 体 是 打开 绥 存 转发 响应 的 关键 ， 下 面 的 章节 中 我 们 会 一 直 与 它 “ 打 3 


12.8.3 ”转发 啊 应 的 包 体 


在 图 12-9 中 我 们 看 到 ， 处 理 上 游 读 事件 的 方法 是 ngx_http_upstream_process_upstream， 处 





ngx_int_t ngx_event_pipe(ngx_event pipe t *p, ngx_int_t do_write) 
































其 中 ，p 参 数 正 是 负责 转发 响应 的 ngx_event_pipe_t 结 构 体 ， 而 do_write 则 是 标志 位 ， 其 大 











下 面 介 绍 图 12-10 中 的 10 个 步骤 。 





























1) 检查 do_write 标 志 位 ， 如 果 do_write 为 0， 则 直接 跳 到 第 5 步 开始 读 取 上 游 服务 器 发 来 上 





2) 调用 ngx_event_pipe_write_to_downstream 方 法 《参见 12.8.5 节 ) 向 下 游客 户 端 发 送 响 上 









1 ) 检测 do write 
标志 位 












[do_write 标志 位 为 1] [dowrite 慰 志 位 为 0] 


2) 调 用 ngx_event_pipe_write_to_downstream 
方法 向 下 游 发 送 响 应 
[检查 方法 返回 值 ] 


’ 


[返回 NGX_OK] [返回 NGCX_BUSY] 


[返回 NGX_ABORT ] 


5) 调 用 ngx_event_pipe_read_upstream 


方法 由 上 游 读 取 响 应 
[检查 方法 返回 值 ] 





[返回 NGX_ABORT] 


3) 返 回 
NGX_ABORT 


[返回 NGCXOK] ” [没有 可 读 内 容 ] 
6) 设置 do write 


标志 位 为 1 


TO Po RN 


8) 将 下 游 写 事件 添加 到 
oz 器 下 





定时 : 
4) 返 回 
9) 将 上 游 读 事件 添加 到 NGX_OK 
epoll 中 
10) 将 上 游 读 事件 添加 到 关 





时 种 


图 12-10 ”ngx_event_pipe 方 法 的 流程 图 


3) 











ngx_event_pipe 方 法 结束 ， 返 回 NGX_ABORT 表 示 请 求 处 理 失败 。 





4) 








ngx_event_pipe 方 法 结束 ， 返 回 NGX_OK 表 示 本 次 暂 不 往 下 执行 


5) 








调用 ngx_event_pipe_read_upstream 方 法 (参见 12.8.4 节 ) 读 取 上 游 服务 器 的 响应 ， 同 [ 


6) 设置 do_write 标 志 位 为 1， 继 续 跳 到 第 1 步 向 下 游 发 送 刚 收 到 的 





上 游 啊 应 ， 








mh 
tn 
a 
[i 
请 


7) 调用 ngx_handle_read_event 方 法 将 上 游 的 读 


次 纯 - 





件 添加 到 epoll 中 ， 等 待 下 一 次 接收 到 上 


8) 调用 ngx_add_timer 方 法 将 上 游 的 读 


EE 





l 件 添加 到 定时 器 中 ， 超 时 时 间 就 是 ngx_event_pi 


9) 调用 ngx_handle_write_event 方 法 将 下 游 的 写 事件 添加 到 epoll 中 ， 等 待 下 一 次 可 以 向 


10) 调用 ngx_add_timer 方 法 将 下 游 的 写 事件 添加 到 定时 器 中 ， 











+ 


超时 时 间 就 是 ngx_event T 





口 刁 
于 上 


可 以 看 到 ，ngx_event_pipe 方 法 在 没有 涉及 缓存 细节 的 情况 下 设计 了 转发 啊 应 的 流 和 





12.8.4 ngx_event_pipe_read_upstream 方 法 





ngx_event_pipe_read_upstream 方 法 负责 接收 上 游 的 响应 ， 在 这 个 过 程 中 会 涉及 以 下 4 种 愉 











* 接收 响应 头 部 时 可 能 接收 到 部 分 包 体 。 


. 如 果 没 有 达到 bufs.num 上 限 ， 那 么 可 以 分 配 bufs.size 大 小 的 内 存 块 充当 接收 缓冲 区 。 


` 如 果 恰 好 下 游 的 连接 处 于 可 写 状态 ， 则 应 该 优先 发 送 响应 来 清理 出 空闲 缓冲 区 。 


如 果 缓 冲 区 全 部 写 满 ， 则 应 该 写 入 临时 文件 。 


这 4 种 情况 会 造成 ngx_event_pipe_read_upstream 方 法 较为 复杂 ， 特 别 是 任何 一 个 ngx_buf_ 








[检查 preread_bufs 预 读 缓冲 区 链表 指针 是 否 为 空 ] 





[preread_bufs 不 为 空 ] 


[ preread_bufs 为 空 , 检查 free_raw_bufs 链 表 指 针 是 否 为 空 ] 


1 ) 准备 处 理 preread_bufs 
中 存放 包 体 的 缓冲 区 





[free_raw_bufs 不 为 空 ] 


[free_rawbufs 为 空 , 检查 allocated 是 否 小 于 bufs.num 1] 
2) 使 用 free_raw_bufs 
接收 上 游 响 应 





[已 分 配 缓冲 区 数目 allocated 小 于 bufs.num 1] 


[allocated 大 于 或 等 于 bufs.num, 检查 是 否 可 向 下 游 发 送 响 应 ] 
) 分 配 新 的 缓冲 区 
接收 上 游 响应 











[Nginx 与 下 游 的 连接 上 可 写 事件 已 经 准备 好 ] 


[下 游 写 事件 不 可 用 , 检查 临时 文件 是 否 达 到 max_temp_file _size] 
4 )upstream_blocked 标 志 位 置 为 1， 
返回 NGX_OK 
















[临时 缓存 文件 未 达到 上 限 ] 


5) 将 上 游 响 应 写 入 
临时 文件 


备 讨 牛 大 小 已 达 至 市 
[临时 文件 大 小 已 达到 限制 ] 四 调用 recv chain 
方法 接收 上 游 响 应 包 体 


7) 将 新 接收 到 的 组 
free_rawbufs 链表 末 


各 


图 12-11 使 用 缓冲 区 接收 上 游 响 应 的 流程 图 


图 12-11 中 的 步骤 很 清晰 ， 主 要 是 在 寻找 使 用 哪 一 块 缓冲 区 接收 上 游 响应 。 注 意 ， 在 选择 








1) 首先 检查 ngx_event_pipe_t 结 构 体 中 的 preread_bufs 绥 冲 区 〈 若 无 特殊 说 明 ， 以 下 介绍 

















2) 检查 free_raw_bufs 缓 冲 区 链表 ，free_raw_bufs 用 来 表示 一 次 ngx_event_pipe_read_upsti 

















3) 将 已 经 分 配 的 缓冲 区 数量 (allocated 成 员 ) 与 bufs.num 配 置 相 比 ， 如 果 allocated 小 于 Pb- 














4) 检查 Nginx 与 下 游 的 连接 downstream 成 员 ， 检 查 它 的 写 事 件 的 ready 标 志 位 ， 如 果 readi 























5) 检查 临时 文件 中 已 经 写 入 的 啊 应 内 容 长 度 〈( 也 就 是 temp_file->offset) 是 否 达 到 配置 














6) 调用 recv_chain 方 法 接收 上 游 的 响应 。 


7) 将 新 接收 到 的 缓冲 区 置 到 free_raw_bufs 链 表 的 最 后 。 








图 12-11 中 的 这 7 个 步 又 将 会 找 出 一 个 缓冲 区 接收 上 游 的 响应 ， 并 把 这 个 绥 冲 区 添加 到 fre 











图 12-12 展 示 了 ngx_event_pipe_read_upstream 方 法 的 全 部 流程 ， 其 中 主要 包括 一 个 接收 上 
















1) 检查 上 游 连接 是 否 结 束 ， 
或 者 暂 无 可 读 内 容 





[可 以 读 取 上 游 响 应 ] 












结束 ,或 者 暂 不 可 读 ] 


[upstream 
2) 使 用 绥 冲 区 读 
取 上 游 响 应 


[上 游 关 闭 连接 ] 
[有 需要 处 理 的 亦 取 到 的 响应 ] 


3 ) 置 read 
标志 位 为 1 








[返回 NGX_AGAIN] 








4 ) 遍 历 待 处 理 缓冲 区 链表 中 的 
ngx_buf_t 


8) 置 upstream_eof 为 1 
表示 上 游 连接 结 ; 











[直接 返回 NGX_OK 1] 
5 ) 调 用 ngx_event_pipe_remove_ 
shadow_links 方 法 
[检查 读 取 到 的 内 容 是 否 全 部 

保存 在 当前 缓冲 区 中 ] 














9) 检查 上 洲 连 接 
是 否 关闭 


[ 读 取 到 的 内 容 小 于 当前 缓冲 区 大 小 ] 
:或 等 于 当前 缓冲 区 的 大 小 








[ 读 取 到 的 内 容 大 = 


方法 处 理 包 体 


7) 将 free_raw_bufs 
指向 剩余 缓冲 区 






[上 游 连接 关闭 ] 







10) 调用 input_filter 
方法 处 理 包 体 


[检查 free_bufs 标志 位 ] 









[上 游 连接 未 关闭 ] 





[free_bufs 为 1] 
[free_bufs 为 0] 
11) 释放 缓冲 区 


图 12-12 ngx_event_pipe_read_upsttream 方 法 接收 上 游 响应 的 流程 


1) 检查 上 游 连接 是 否 结束 ， 以 及 与 上 游 连接 的 读 事 件 是 否 已 经 就 绪 ， 代 码 如 下 。 


// 这 
3 个 标志 位 的 意义 可 参见 
12.8.1 节 ， 其 中 任 一 个 为 


1 都 表示 上 游 连接 需要 结束 





if (p->upstream eof || p->upstream_error || p->upstream done) { 


// 跳 到 第 


break; 


/如 果 读 事件 的 

ready 标 志 位 为 

06， 则 说 明 没 有 上 游 响 应 可 以 接收 ; 

preread_bufs 预 读 缓冲 区 为 空 ， 表 示 接 收 包 头 时 没有 收 到 包 体 ， 


i 
/ 
if (p->preread bufs == NULL && !p->upstream->read->ready) { 
// 跳 到 第 


如 果 这 两 个 条 件 有 一 个 满足 ， 则 需要 跳 到 第 9 步 ， 





2) 接收 上 游 响 应 ， 这 一 步 实 际 上 就 是 执行 图 12- 





3) 置 read 标 志 位 为 1， 表 示 接 收 到 的 包 体 竺 处 理 


或 者 收 到 过 包 体 但 已 经 处 理 过 了 








准备 结束 ngx_event_pipe_read_upstrean 





11 中 列 出 的 7 个 步骤 。 它 会 导致 3 种 结果 : 


o 


4) 从 接收 到 的 缓冲 区 链表 中 取出 一 块 ngx_buf _t 绥 冲 区 。 








5) 调用 ngx_event_pipe_remove_shadow_links 方 法 将 这 块 缓冲 区 中 的 shadow 域 释放 掉 ，E 














6) 检查 本 次 读 取 到 的 包 体 是 否 大 于 或 等 于 缓冲 区 的 剩余 空间 大 小 。 这 一 步 的 意义 在 于 ， 





7) 将 本 次 接收 到 的 缓冲 区 添加 到 free_raw_bufs 链 表 末 尾 ， 继 续 第 1 步 执 行 这 个 大 循环 。 


8) 将 upstream_eof 标 志 位 置 为 1， 表 示 上 游 服 务 器 已 经 关闭 了 连接 。 








9) 检查 upstream_eof 和 upstream_error 标 志 位 是 否 有 任意 一 个 为 1， 如 果 有 ， 则 说 明 上 游 主 























10) 再 次 调用 input_filter 方 法 处 理 free_raw_bufs 中 的 缓冲 区 (类 似 第 6 步 ， 但 这 次 只 处 理 1 











11) 检查 free_bufs 标 志 位 ， 如 果 free_bufs 为 1， 则 说 明 需 要 尽快 释放 缓冲 区 中 用 到 的 内 存 


可 以 看 到 ，ngx_event_pipe_read_upstream 方 法 将 会 把 接收 到 的 响应 存放 到 内 存 或 者 磁盘 - 





12.8.5 ngx_event_pipe_write_to_downstream 方 法 








ngx_event_pipe_write_to_downstream 方 法 负责 把 in 链 表 和 out 链 表 中 管理 的 缓冲 区 发 送 给 - 





下 面 详 细 分 析 一 下 图 12-13 中 的 13 个 步骤 。 











1) 首先 检查 上 游 连 接 是 否 结束 ， 判 断 依据 与 图 12-12 中 的 第 1 步 非常 相似 ， 检 查 upstream 





让 





2) 调用 output_filter 方 法 把 out 链 对 





中 的 缓冲 区 发 送 到 下 游客 户 端 。 








3) 调用 output_filter 方 法 把 in 链 表 中 的 缓冲 区 发 送 到 下 游客 户 端 。 

















4) 将 downstream_done 标 志 位 置 为 1〈 目 前 没有 任何 意义 ) ，ngx_event_pipe_write_to_do 




















5) 计算 busy 绥 冲 区 中 竺 发送 的 响应 长 度 ， 检 查 它 是 否 超过 busy_size 配 置 ， 如 果 其 大 于 马 





























6) 首先 检查 out 链 表 是 否 为 空 ， 如 果 out 中 有 内 容 ， 那 么 立刻 跳 到 第 7 步 准备 发 送 out 组 冲 | 


























7) 取出 out 链 表 首 部 的 第 一 个 ngx_buf t 缓 冲 区 ， 检 查 待 发 送 的 长 度 加 上 这 个 缓冲 区 后 是 ， 











[上 游 连接 已 经 结 





i 2) 疝 下 游 发 天 
[ 写 事 们 准备 好 ] 
5 ) 计 算 busy 
3) 向 下 游 发 送 
in 缓冲 区 







缓冲 区 大 小 


[busy 缓冲 区 未 超过 busy_sizel 


4) 设 置 downstream_down 










标志 位 为 1 
6) 检 测 out 和 in 
缓冲 区 链表 





[busy 缓冲 区 超过 busy size] 











[in 链表 不 为 空 ] 
[in、 out 链表 为 空 
或 竺 发送 内 容 超 过 


busy_size] 


[out 链表 不 为 空 ] 

7 ) 使 用 out 链表 首 个 缓冲 区 
作为 发 送 内 容 
[ 写 事件 未 准备 好 ] 


缓 惠 区 作 炎 发送 内 容 





9) 将 刚 处 理 的 buf 
设置 到 out 链 表 


10) 检 查 out 缓冲 区 以 及 之 前 各 步骤 


是 否 有 内 容 需要 发 送 











[没有 需要 发 送 的 内 容 ] 
[有 内 容 需 要 发 送 ] 


11) 调 用 output_filter 
发 送 啊 应 


12) 调 用 ngx__chain date_chains 
缓冲 区 


方法 更 新 


13) 释 放 free 





图 12-13 ngx_event_pipe_wtite_to_downstream 方 法 的 流程 图 








8) 取出 in 链 表 首 部 的 第 一 个 缓冲 区 准备 发 送 ， 所 有 步 又 与 第 7 步 相 同 。 





















































9) 将 刚才 调用 ngx_event_pipe_free_shadow_raw_buf 方 法 处 理 过 的 缓冲 区 再 添加 到 out 链 


















































10) 检查 out 链 表 以 及 之 前 各 个 步骤 中 是 否 有 需要 发 送 的 内 容 〈 其 实 是 通过 一 个 局 部 变量 











11) 调用 output_filter 方 法 癌 下 游 发 送 out 缓 冲 区 。 








12) 调用 ngx_chain_update_chains 方 法 更 新 free、busy、out 绥 冲 区 。 在 图 12-8 的 第 4 步 中 证 





13) 遍历 free 链 表 中 的 缓冲 区 ， 释 放 缓 冲 区 中 的 shadow 域 ， 这 样 ， 这 些 暂 不 使 用 的 缓冲 [ 























至 此 ，buffering 配 置 为 1 时 转发 上 游 响应 到 下 游 的 整个 流程 就 全 部 介绍 完了 ， 它 的 流程 复 


12.9 结束 upstream 请 求 


当 Nginx 与 上 游 服 务 器 的 交互 出 错 ， 或 者 正常 处 理 完 来 自 上 游 的 啊 
应 时 ， 就 需要 结束 请 求 了 。 这 时 当然 不 能 调用 第 11 章 中 介绍 的 
ngx_http_finalize_request 方 法 来 结束 请 求 ， 这 样 upstream 中 使 用 到 的 资源 

《如 与 上 游 间 建立 的 TCP 连 接 ) 将 无 法 释放 ， 事 实 上 ，upstream 机 制 提 
供 了 一 个 类 似 的 方法 ngx_http_upstream_finalize_request 用 于 结 
upstream 请 求 ， 在 12.9.1 节 中 将 会 详细 介绍 这 个 方法 。 除 了 直接 调用 
ngx_http_upstream_finalize_request 方 法 结束 请 求 以 外 ， 还 有 两 种 独特 的 
结束 请 求 方法 ， 分 别 是 ngx_http_upstream_cleanup 方 法 和 


ngx_http_upstream_next 方 法 。 


在 启动 upstream 机 制 时 ，ngx_http_upstream_cleanup 方 法 会 挂 载 到 请 
求 的 cleanup 链 表 中 参见 图 12-2 的 第 3 步 ) ， 这 样 ，HTTP 框 架 在 请 求 结 
束 时 就 会 调用 ngx_http_upstream_cleanup 方 法 《参见 11.10.2 节 
ngx_http_free_request 方 法 的 流程 ) ， 这 保证 了 
ngx_http_upstream_cleanup 一 定 会 被 调用 。 而 ngx_http_upstream_cleanup 
方法 实际 上 还 是 通过 调用 ngx_http_upstream_finalize_request 来 结束 请 求 
的 ， 如 下 所 示 。 





static void ngx_http_upstream cleanup(void *data) 


ngx_http_request t *r = data,; 


ngx_http_upstream t *u = r->upstream; 


/* 最 终 还 是 调用 
ngx_http_upstream_finalize_request 方 法 来 结束 请 求 ， 注 意 传 递 的 是 
NGX_DONE 参 数 


Sf 


} 


ngx_http_upstream finalize_request(r, u, NGX_DONE); 





当 处 理 请 求 的 流程 中 出 现 错误 时 ， 往 往 会 调用 
ngx_http_upstream_next 方 法 。 例 如 ， 在 图 12-5 中 ， 如 果 在 接收 上 游 服 务 
器 的 包头 时 出 现 错误 ， 接 下 来 就 会 调用 该 方法 ， 这 是 因为 upstream 机 制 
还 提供 了 一 个 较为 灵活 的 功能 : 当 与 上 游 的 交互 出 现 错误 时 ，Nginx 并 
不 想 立 刻 认为 这 个 请 求 处 理 失败 ， 而 是 试图 多 给 上 游 服务 器 一 些 机 会 ， 
可 以 重新 问 这 人 台 或 者 另 一 台 上 游 服 务 堪 发 起 连接 、 发 送 请 求 、 接 收 啊 
应 ， 以 避免 网 络 故 障 。 这 个 功能 可 以 帮助 HTTP 模 块 实现 人 简单 的 负载 均 
衡 机 制 (《 如 最 常见 的 HTTP 有 反问 代理 模块 )。 而 该 功能 正 是 通过 
ngx_http_upstream_next 方 法 实现 的 ， 因 为 该 方法 在 结束 请 求 之 前 ， 会 检 
但 ngx_peer_connection_t 结 构 体 的 tries 成 员 〈 参 见 9.3.2 节 ) 。tries 成 员 会 
初始 化 为 每 个 连接 的 最 大 重 斌 次数， 每 当 这 个 连接 与 上 游 服务 器 出 现 错 
误 时 就 会 把 tries 减 1。 在 出 错时 ngx_http_upstream_next 方 法 首先 会 检查 
tries， 如 果 它 减 到 0， 才 会 真正 地 调用 ngx_http_upstream_finalize_request 
方法 结束 请 求 ， 否 则 不 会 结束 请 求 ， 而 是 调用 











ngx_http_upstream_connect 方 法 重新 问 上 游 发 起 请 求 ， 如 下 所 示 。 





static void ngx_http_upstream next(ngx_http_request t *r, ngx_http_upstream t *u, nc 


{ 


/* 只 有 向 这 台 上 游 服 务 器 的 重 试 次 数 





tries 减 为 

0 时 ， 才 会 真正 地 调用 

ngx_http_upstream_finalize_request 方 法 结束 请 求 ， 否 则 会 再 次 试图 重新 与 上 游 服务 器 交互 ， 这 个 功能 米 
HTTP 模 块 实现 简单 的 负载 均衡 机 制 。 

Uu->conf->next_upstream 表 示 的 含义 在 

12 .1.3 节 中 已 介绍 过 ， 它 实际 上 是 一 个 

32 位 的 错误 码 组 合 ， 表 示 当 出 现 这 些 错 误 码 时 不 能 直接 结束 请 求 ， 需 要 向 下 一 台 上 游 服务 器 再 次 重 发 

*/ 


If (u->peer.tries == 0 || !(u->conf->next_upstream & ft_type)) 


ngx_http_upstream finalize_request(r, u, status); 
return; 


} 
// 如 果 与 上 游 间 的 


TCP 连 接 还 存在 ， 那 么 需要 关闭 


if (u->peer.connection) { 
ngx_close_connection(u->peer.connection); 
Uu->peer.connection = NULL; 


// 重新 发 起 连接 ， 参 见 





142.3 鞍 


ngx_http_upstream connect(r, u); 





下 面 来 看 一 下 ngx_http_upstream_finalize_request 到 底 做 了 些 什 么 工 
{Es 


ngx_http_upstream_finalize_request 方 法 还 是 会 通过 调用 HTTP 框 架 提 
供 的 ngx_http_finalize_request 方 法 释放 请 求 ， 但 在 这 之 前 需要 释放 与 上 
游 交 互 时 分 配 的 资源 ， 如 文件 句柄 、TCP 连 接 每 。 它 的 源 代码 很 简单 ， 
下 面 直接 列举 其 源 代码 说 明 它 所 做 的 工作 。 








static void ngx_http_upstream_finalize_request(ngx_http_redquest_t *r, 
ngx_http_upstream t *u, ngx_int_t rc) 
{ 


ngx_time tt *tp; 
// 将 


Cleanup 指 向 的 清理 资源 回调 方法 置 为 


NULL 空 指针 


if (u->cleanup) { 
*Uu->cleanup = NULL; 
u->cleanup = NULL; 


} 
// 释放 解析 主机 域名 时 分 配 的 资源 


if (u->resolved && U->resolved->ctx) { 
ngx_resolve_name_done(u->resolved->ctx); 
U->resolved->ctx = NULL; 


If (u->state && Uu->state->response sec) { 
// 设置 当前 时 间 为 


HTTP 响 应 结 来 时 间 


tp = ngx_timeofday(); 

U->state->response_sec = tp->sec - U->state->response_sec; 
U->State->response_msec = tp->msec - U->State->response_msec 
if (u->pipe) { 


U->Sstate->response_length = u->pipe->read_length; 
} 

} 

/* 表 示 调 用 
HTTP 模 块 负责 实现 的 
finalize_request 方 法 。 
HTTP 模 块 可 能 会 在 
Upstream 请 求 结束 时 执行 一 些 操作 


WA 
uU->finalize_request(r, rc); 
A* 如 果 使 用 了 


TCP 连 接 池 实现 了 
free 方 法 ， 那 么 调用 


free 方 法 (如 





ngx_http_upstream_free_round_robin_peer) 释放 连接 资源 


Wy 
If (u->peer.free) { 
U->peer .free(&u->peer, u->peer.data, 0); 


} 
// 如 果 与 上 游 间 的 
TCP 连 接 还 存在 ， 则 关闭 这 个 


TCP 连 接 


If (u->peer.connection) { 
ngx_close_connection(u->peer .connection); 
} 


U->peer .connection = NULL; 
If (Uu->store && U->pipe && Uu->pipe->temp_file 
&& U->pipe->temp_file->file.fd != NGX_INVALID_FILE) 
/* 如 果 使 用 了 磁盘 文件 作为 缓存 来 向 下 游 转发 响应 ， 则 需要 删除 用 于 缓存 响应 的 临时 文件 


*/ 
if (ngx_delete file(u->pipe->temp_file->file.name.data) 


== NGX_FILE_ERROR) 
ngx_log_error(NGX_LOG_CRIT，r->connection->1og，ngx_errno，ngx_delete_fi 


U->pipe->temp_file->file,name.data)， 


} 
, 和 
/* 如 果 已 经 向 下 游客 户 端 发 送 了 
HTTP 响 应 头 部 ， 却 出 现 了 错误 ， 那 么 将 会 通过 下 面 的 


ngx_http_send_special(r，NGX_HTTP_LAST ) 将 头 部 全 部 发 送 完毕 


*/ 
If (u->header_sent && rc != NGX_HTTP_REQUEST_TIME_OUT 
&& (rc == NGX_ERROR || rc >= NGX_HTTP_SPECIAL_RESPONSE ) ) 
{ 
rc = 0; 
} 
if (rc == NGX_DECLINED) { 
return; 
} 
r->connection->lo0g->action = "sending to client",; 
if (rc == 0) 
{ 
rc = ngx_http_send_ special(r, NGX_HTTP_LAST); 
} 
/* 最 后 还 是 通过 调用 
HTTP 框 架 提供 的 


ngx_http_finalize_redquest 方 法 来 结束 请 求 
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} 


二 一 


ngx_http_finalize_request(r, rc); 


介 I40 加 富 





本 章 介 绍 的 upstream 机 制 也 属于 HTTP 框 架 的 一 部 分 ， 它 同样 是 基于 
事件 框架 实现 了 异步 访问 上 游 服务 器 的 功能 ， 同 时 ， 它 并 不 满足 于 仅仅 
帮助 应 用 级 别 的 HTTP 模 块 基于 TCP 访 问 上 游 ， 而 是 提供 了 非常 强大 的 
转发 上 游 响 应 功能 ， 而 且 在 转发 方式 上 更 加 灵活 、 高 效 ， 并 且 对 于 内 存 
的 使 用 相当 节省 ， 这 些 功 能 帮助 Nginx 的 ngx_http_proxy_module 模 块 实 
现 了 强大 的 反 向 代理 功能 。 同 时 ， 配 合 着 
ngx_http_upstream_ip_hash_module 或 者 Round Robin 相 关 的 代码 〈 它 们 负 





责 管理 ngx_peer_connection_t 上 游 连 接 ) ，ngx_http_upstream_next 方 法 


还 可 以 帮助 HTTP 模 块 实现 简单 的 负载 均衡 功能 。 


由 于 upstream 机 制 属 于 HTTP 框 染 ， 所 以 它 仪 抽象 出 了 通用 代码 ， 而 
尽量 地 把 组 装 发 往 上 游 请 求 、 解 析 上 游 啊 应 的 部 分 都 交 给 使 用 它 的 
HTTP 模 块 实现 ， 这 使 得 使 用 upstream 的 HTTP 模 块 不 会 太 复 杂 ， 而 性 能 
却 非常 高 效 ， 算 是 在 灵活 性 和 简单 性 之 间 找 到 了 一 个 平衡 点 。 在 阅读 完 
本 章 后 ， 我 们 就 有 可 能 写 出 非常 强大 的 访问 第 三 方 服务 器 的 代码 了 ， 在 
这 个 过 程 中 ， 尽 量 使 用 upstream 已 经 提供 的 各 种 功能 ， 将 会 简化 HTTP 模 
块 的 开发 过 程 。 


第 13 半 ”邮件 代理 模块 


本 章 将 说 明 Nginx 官 方 提供 的 一 系列 邮件 模块 ， 这 些 邮件 模块 配合 
Nginx 事 件 框架 共同 构建 了 支持 POP3、SMTP、IMAP 这 3 种 协议 的 邮件 
代理 服务 器 ， 它 们 把 邮件 代理 服务 器 的 主要 功能 抽象 成 一 个 类 似 于 
HTTP 框 架 的 邮件 框架 ， 以 灵活 地 支持 Nginx 扩 展 更 多 的 邮件 协议 ， 而 
POP3、SMTP、IMAP 模 块 将 作为 普通 的 邮件 模块 使 用 这 套 框 保 。 作 为 
邮件 代理 服务 器 的 Nginx 虽 然 也 访问 上 游 服务 器 ， 但 由 于 它 不 使 用 HITP 
框架 ， 所 以 无 法 使 用 第 12 章 介绍 的 upstream 机 制 ， 然 而 “邮件 代理 ”其 实 
同样 具有 部 分 的 反 向 代理 功能 ， 本 章 13.7 节 介绍 的 透 传 TCP 部 分 其 实 也 
有 点 像 一 个 简化 版 的 upstream 机 制 。 


本 章 首 先 介绍 邮件 代理 功能 到 底 做 了 哪些 事情 ， 接 下 来 会 分 析 
Nginx 如 何 实现 邮件 代理 功能 。 实 际 上 ， 本 章 更 像 是 第 10 章 ~ 第 12 章 的 简 
化 版 本 ， 所 以 在 本 章 中 将 不 会 再 次 描述 曾经 介绍 过 的 如 何 异 步 地 、 无 阻 
塞 地 提供 服务 ， 以 及 如 何 使 用 epoll、 定 时 器 等 事件 框架 。 读 者 也 应 当 熟 
悉 Nginx 的 这 套 设 计 方 法 了 ， 因 此 本 章 仅 会 描述 邮件 模块 的 主要 阶段 ， 
不 会 深入 细节 。 另 外 ， 本 章 也 不 会 详细 说 明 POP3、SMTP、IMAP， 
为 Nginx 并 非 真正 的 邮件 服务 器 。 本 音 的 重点 在 于 了 解 邮件 代理 服务 器 
的 使 用 方法 ， 以 及 应 该 如 何 扩展 邮件 代理 模块 的 功能 ， 同 时 了 解 通过 邮 
件 模块 继续 熟悉 Nginx 事 件 框架 的 用 法 ， 继 而 熟悉 如 何 利用 它 开 发 高 性 





能 服务 器 。 


13.1 邮件 代理 服务 器 的 功能 


在 第 8 对 中 介绍 过 邮件 模块 ， 它 提供 了 邮件 代理 服务 器 的 功能 。 什 
么 是 邮件 代理 服务 器 ? 顾名思义， 它 不 会 提供 实际 的 邮件 服务 器 功能 ， 
而 是 把 客户 问 的 请 求 代 理 到 上 游 的 邮件 服务 器 中 。 那 么 ， 客 户 问 为 何不 
直接 访问 真正 的 邮件 服务 器 ， 反 而 多 此 一 举 地 访问 邮件 代理 服务 器 呢 ? 
原因 可 以 在 后 续 章 节 描 述 的 Nginx 实 现 中 找到 ， 其 中 最 重要 的 是 Nginx 并 
不 是 简单 地 透 传 邮件 协议 到 上 游 ， 它 还 有 一 个 认证 的 过 程 ， 如 图 13-1 所 


作 \。 





从 图 13-1 中 可 以 看 出 ，Nginx 在 与 下 游客 户 端 交互 过 程 中 ， 还 会 访 
问 认 证 服务 器 ， 只 有 认证 服务 器 通过 了 并 且 被 告知 Nginx 上 游 的 邮件 服 
务 器 地 址 后 ，Nginx 才 会 同上 游 的 邮件 服务 器 发 起 通信 请 求 。 同 时 ， 
Nginx 可 以 解析 客户 端的 协议 获得 必要 的 信息 ， 接 下 来 它 还 可 以 根据 客 
户 端 发 来 的 信息 快速 、 独 立地 与 邮件 服务 器 做 简单 的 认证 交互 ， 之 后 才 
会 开始 在 上 、 下 游 之 间 透 传 TCP 流 。 这 些 行为 都 意味 着 Nginx 的 高 并 发 
特性 将 会 降低 上 游 邮 件 服务 器 的 并 友 压 力 。 





oy 


POP3 邮 件 服 务 需 IMAI | i 务 器 SMTP 邮 件 服 务 器 


Noinx HTTP 认 证 服务 侨 


. 


邮件 客户 病 


图 13-1 Nginx 在 邮件 代理 场景 中 的 位 置 





Nginx 与 下 游客 户 跨 、 上 游 邮 件 服务 器 间 都 是 使 用 邮件 协议 ， 而 与 
认证 服务 器 之 间 却 是 通过 类 似 HTTP 的 形式 进行 通信 的 。 例 如， 发 往 认 
证 服务 器 的 请 求 如 下 所 示 : 





GET /auth HTTP/1.0 

Host: auth.server.hostname 
Auth-Method: plain 
Auth-User: user 

Auth-Pass: password 
Auth-Protocol: imap 
Auth-Login-Attempt: 1 
Client-IP: 192.168.1.1 





而 认证 服务 器 会 返回 最 常见 的 成 功 啊 应 ， 即 类 似 下 面 的 字符 流 : 





HTTP/1.0 200 OK 
Auth-Status: OK 
Auth-Server: 192.168.1.10 
Auth-Port: 110 

Auth-User: newname 





当然 ， 认 证 服务 器 的 返回 要 复杂 得 多 。 由 于 本 章 既 不 会 介绍 认证 服 
务 右 如 何 实现 ， 也 不 会 介绍 上 游 的 邮件 服务 器 如 何 实现 ， 所 以 对 协议 部 


分 不 会 继续 深入 介绍 。 


一 般 情 况 下 ， 和 客户 端 发 起 的 邮件 请 求 在 经 过 Nginx 这 个 邮件 代理 服 
务 龙 后 ， 网 络 通 信 过 程 如 图 13-2 所 示 。 


从 网 络 通 信 的 角度 来 看 ，Nginx 实 现 邮件 代理 功能 时 会 把 一 个 请 求 
分 为 以 下 4 个 阶段 。 


` 接收 并 解析 客户 端 初始 请 求 的 阶段 。 


. 向 认证 服务 器 验证 请 求 合法 性 ， 并 获取 上 游 邮 件 服务 器 地 址 的 阶 


段 。 
- Nginx 根 据 用 户 信 息 多 次 与 上 游 邮 件 服务 器 交互 验证 合法 性 的 阶 
段 。 


. Nginx 在 客户 端 与 上 游 邮 件 服务 器 间 纯 粹 透 传 TCP 流 的 阶段 。 


由 此 可 以 了 解 到 ， 这 些 Nginx 邮 件 模块 的 目的 非常 明确 ， 就 是 使 用 
事件 框架 在 大 量 并 发 连接 下 高 效 地 处 理 这 4 个 阶段 的 请 求 。 


| | 


| 用 户 请 求 “| 





1 
1 
| 
类 HTTP 认 证 请 求 | 






认证 响应 


1 
发 起 TCP 连 接 


欢 迎 消 息 


验证 用 户 名 ,密码 等 














POP 3 
SMTP、IMAP 
等 协议 需要 响应 
| 
都 不 相同 






Nginx 将 开始 在 | | | 转发 上 游 的 响应 
客户 端 与 邮件 服 
务 器 之 间 双 向 透 | | | 转发 上 游 的 请 求 
传 TCP 流 


啊 应 





图 13-2 ”邮件 代 理 功能 的 示意 序列 图 


为 了 让 读者 对 邮件 代理 服务 器 有 直观 的 认识 ， 下 面 再 来 看 看 
nginx.conf 配 置 文件 。 邮 件 模块 定义 的 nginx.conf 配 置 文件 与 HITP 模 块 非 
第 相似 。 例 如 ， 和 常见 的 配置 可 能 就 像 下 面 的 这 段 配置 一 样 。 





mail { 


// 邮件 认证 服务 器 的 访问 


URL 
auth_http IP:PORT/auth.php; 
// 当 透 传 上 、 下 游 间 的 


TCP 流 时 ， 每 个 请 求 所 使 用 的 内 存 缓冲 区 大 小 


proxy_buffer 4k; 
server { 
作对 于 


POP3 协 议 ， 通 常 都 是 监听 


110 端 口 。 


POP3 协 议 接 收 初始 客户 端 请 求 的 缓冲 区 固定 为 


128 字 节 ， 配 置 文件 中 无 法 设置 


“7 
listen 110; 
protocol pop3; 


proxy on; 
} 
server { 

// 对 于 


IMAP， 通 常 都 是 监听 


143 端 口 


listen 143; 
protocol imap; 
// 设置 接收 初始 客户 端 请 求 的 缓冲 区 大 小 


Imap_client_buffer 4k; 
proxy on; 

} 

server { 
// 对 于 


25 端 口 


listen 25; 

protocol smtp; 

proxy on; 

// 设置 接收 初始 客户 端 请 求 的 缓冲 区 大 小 


smtp_client_buffer 4k; 


mail{} 块 下 的 配置 项 将 会 被 本 章 介 绍 的 邮件 模块 所 使 用 。 就 像 
HTTP 模 块 中 的 配置 一 样 ， 直 属于 mail{} 块 下 的 配置 称 为 main 级 别 的 配 
置 ， 而 在 server{} 块 下 的 配置 则 称 为 svr 配 置 ( 不 使 用 HTTP， 故 没有 loc 
级 别 的 配置 ) 。 


13.2 ”邮件 模块 的 处 理 框架 


本 节 首 先 会 从 总 体 上 说 明 邮 件 框 染 是 如 何 处 理 请 求 的 ， 接 着 会 介绍 
这 一 新 的 模块 类 型 有 什么 样 的 接口 ， 以 及 应 当 如 何 定义 ， 最 后 将 会 简单 


地 说 明 邮 件 框 染 的 初始 化 过 程 。 


13.2.1 一 个 请 求 的 8 个 独立 处 理 阶段 


图 13-2 大 致 介 绍 了 请 求 的 处 理 过 程 ， 而 对 于 邮件 框 染 而 言 ， 通 第 可 
以 把 请 求 的 处 理 过 程 分 为 8 个 阶段 。 这 里 “阶段 ”的 划分 依据 是 什么 呢 ? 
由 于 Nginx 是 异步 的 、 非 阻塞 的 处 理 方式 ， 所 有 负责 独立 功能 的 一 个 
(或 者 几 个 ) 方法 可 能 被 epol 或 者 定时 需 无 数 次 地 驳 动 、 调 度 ， 故 而 可 
以 把 相同 代码 可 能 被 反复 多 次 调用 的 过 程 称 为 一 个 阶段 。 下 面 按照 这 种 
划分 方式 ， 把 请 求 分 为 8 个 阶段 ， 如 图 13-3 所 示 。 














1) 初 始 化 邮件 
青 


端 请 求 阶段 


求 
2 ) 接 收 并 解析 客户 
外 段 





3 ) 向 认证 服务 器 发 起 
TCP 连接 阶段 


4) 癌 认证 服务 器 发 送 


请 求 阶段 








5 ) 接 收 并 解析 认证 服务 需 
的 啊 应 阶段 












6) 向 上 游 邮件 服务 需 
发 起 连接 阶段 


7) 与 邮件 服务 器 交互 
已 知 信息 阶段 





8) 双向 透 传 下 洲 客 户 端 与 上 游 


邮件 服务 右 的 内 容 





图 13-3 ”邮件 框架 中 处 理 一 个 请 求 的 主要 阶段 


这 8 个 阶段 必须 依次 同 下 进行 ， 它 们 的 意义 如 下 。 





1) 当 客户 端 发 起 的 TCP 连 接 建 并 成 功 时 ， 就 会 回调 邮件 框架 初始 
化 时 设 定 的 ngx_mail_init_connection 方 法 ， 在 这 个 方法 中 会 初始 化 将 要 
用 到 的 数据 结构 ， 并 设置 下 一 个 阶段 的 处 理 方法 。 





2) 接收 、 解 析 客 户 端的 请 求 。 这 个 阶段 会 读 取 客 户 端 发 来 的 TCP 
流 ， 并 使 用 状态 机 解析 它 ， 如 宁 解 析 后 发 现 已 接收 到 完整 的 请 求 ， 则 进 
入 下 一 阶段 ， 否 则 ， 将 会 继续 把 连接 上 的 读 事 件 添加 到 epoll 中 ， 并 等 待 
epol 的 下 一 次 调度 ， 以 便 继 续 读 取 客 户 端 请 求 。 





3) 解析 到 完整 的 请 求 后 ， 就 需要 问 认证 服务 占 发 起 类 似 HTTP 的 请 
求 来 验证 请 求 是 否 合 法 。Nginx 与 认证 服务 占 间 仍然 是 通过 TCP 通 信 
的 ， 发 起 三 次 握手 自然 算是 一 个 独立 的 阶段 。 





4) 当 Nginx 与 认证 服务 器 成 功 建 并 TCP 连接 时 ， 
ngx_mail_auth_http_module 模 块 将 会 构造 、 发 送 请 求 到 认证 服务 器 。 在 
13.4.3 节 中 将 要 介绍 的 ngx_mail_auth_http_write_ handler 方 法 会 确保 全 部 
的 请 求 都 发 送 到 认证 服务 器 中 。 





5) Nginx 接 收 认 证 服务 器 的 啊 应 是 通过 
ngx_mail_auth_http_read_handler 完 成 的 ， 在 该 方法 中 ， 每 接收 一 部 分 啊 








应 都 要 使 用 状态 机 来 解析 ， 在 接收 完整 的 啊 应 〈 包 括 啊 应 行 和 HTTP 头 
部 ) 后 ， 还 会 分 析 啊 应 结果 以 确定 请 求 是 否 合法 ， 如 果 合 法 ， 将 继续 执 
行 下 一 阶段 。 


6) 这 一 阶段 将 从 认证 服务 器 返回 的 啊 应 中 获得 上 游 邮 件 服务 器 的 
地 址 ， 接 着 向 上 游 邮 件 服务 器 及 起 TCP 连 接 。 


7) 在 TCP 连 接 建立 成 功 后 ， 接 下 来 是 Nginx 与 邮件 服务 占 使 用 
POP3、SMTP 或 者 IMAP 交 互 的 阶段 。 这 一 过 程 主要 是 Nginx 将 请 求 中 的 
用 户 、 密 码 、 发 件 人 、 收 件 人 等 信息 传递 给 邮件 服务 器 ， 这 个 过 程 是 双 
向 的 ， 直 到 Nginx 认 为 邮件 服务 器 同意 继续 向 下 进行 时 ， 才 会 继续 下 一 
阶段 。 








8) 这 一 阶段 是 最 主要 的 透 传 邮件 协议 阶段 。 只 要 Nginx 收 到 下 游客 
户 端的 TCP 流 《无 论 是 哪 一 种 邮件 协议 ) ， 会 原封 不 动 地 转发 给 上 游 的 
邮件 服务 器 ， 同 样 ， 如 果 收 到 上 游 的 TCP 流 ， 也 会 原样 转发 给 下 游 。 


邮件 框 染 的 目标 就 是 健壮 、 高 效 地 处 理 这 8 个 阶段 。 


13.2.2 ”邮件 类 模块 的 定义 





在 第 8 章 说 过 ， 每 一 个 Nginx 模 块 都 会 使 用 ngx_module_t 结 构 体 来 表 
示 ， 而 ngx_module t 中 的 ctx 成 员 将 指 辐 各 种 模块 的 特有 接口 。 


首先 介绍 的 邮件 模块 是 NGX_CORE_MODULE 类 型 的 
ngx_mail_module 模 块 ， 它 定义 了 一 种 新 的 模块 类 型 ， 叫 做 
NGX_MAIL _MODULE。 同 时 ， 它 会 管理 所 有 NGX_MAIL_MODULE 类 
型 的 邮件 模块 。 这 些 邮 件 模 块 的 ctx 成 员 指 向 的 抽象 接口 叫做 
ngx_mail_module t， 如 下 所 示 。 





typedef struct { 
// POP3、 


SMTP、 


IMAP 邮 件 模块 提取 出 的 通用 接口 


ngx_mail_ protocol t *protocol; 
/* 创 建 用 于 存储 


main 级 别 配 置 项 的 结构 体 ， 该 结构 体 中 的 成 员 将 保存 直属 于 


mail{} 块 的 配置 项 参数 


* 

/ 

void *(*create main conf)(ngx_conf_t *cf); 
/* 解 析 完 


main 级 别 配 置 项 后 被 回调 


*/ 
char *(*init main conf)(ngx_conf_t *cf, void *conf); 
/创建 用 于 存储 


Srv 级 别 配 置 项 的 结构 体 ， 该 结构 体 中 的 成 员 将 保存 直属 于 


server{]} 块 的 配置 项 参数 


WA 
void *(*create srv_conf)(ngx_conf_t *cf); 
A*SVr 级 别 可 能 存在 与 


main 级 别 同名 的 配置 项 ， 该 回调 方法 会 给 具体 的 邮件 模块 提供 一 个 手段 ， 以 便 从 


prev 和 


conf 参 数 中 获取 到 已 经 解析 完毕 的 


main 和 和 


SrVv 配 置 项 结构 体 ， 自 由 地 重新 修改 它们 的 值 


*/ 
char *(*merge_ srv_conf)(ngx_conf_t *cf, void *prev, void *conf); 
} ngx_mail] module_t; 





每 一 个 邮件 模块 都 会 实现 ngx_mail_module_t 接 口 。 除 了 最 上 面 的 
protocol 成 员 以 外 ， 其 实 ngx_mail_ module t 与 ngx_http_module_t 非 常 相 
似 ， 当 然 ， 那 些 同 名 成 员 的 功能 也 是 相似 的 。 下 面 看 一 下 这 个 protocol 
接口 定义 了 哪些 内 容 。 





typedef struct ngx_mail_protocol s ngx_mail_protocol t; 
// 4 个 


POP3、 


SMTP、 


IMAP 等 应 用 级 别 的 邮件 模块 所 要 实现 的 接口 方法 


typedef void (*ngx_mail_init_session_pt)(ngx_mail_session_ t *s, 
ngx_connection_t *c); 
typedef void (*ngx mail init_ protocol pt)(ngx_event _t *rev); 
typedef void (*ngx_ mail auth_ state pt)(ngx_ event t *rev); 
typedef ngx_int t (*ngx_ mail parse command pt) (ngx_mail session t *s); 
struct ngx_mail protocol s { 
// 邮件 模块 名 称 





ngx_str_t name; 
// 当前 邮件 模块 中 所 要 监听 的 最 常用 的 


4 个 端口 


in_port_t port[4]; 
/* 邮 件 模块 类 型 。 目 前 


type 仅 可 以 取 值 为 : 


NGX_MAIL_POP3_PROTOCOL、 


NGX_MAIL_IMAP_PROTOCOL、 


NGX_MAIL_SMTP_PROTOCOL*/ 
ngx_uint_t type; 
// 与 客户 端 建立 起 


TCP 连 接 后 的 初始 化 方法 


ngx_mail init_session pt init_session; 
// 接收 、 解 析 客 户 端 请 求 的 方法 


ngx_mail_init_protocol_pt init_protocol 
// 解析 客户 端 邮件 协议 的 接口 方法 ， 由 


POP3、 


SMTP、 


IMAP 等 邮件 模块 实现 


ngx_mail_parse_command_pt parse_command ; 
// 认证 客户 端 请 求 的 方法 


ngx_mail_auth_state_pt auth_state 
/* 当 处 理 过 程 中 出 现 没有 预见 到 的 错误 时 ， 将 会 返回 





internal_server_error 指 定 的 响应 到 客户 端 


1 
ngx_str_t internal server_error; 





可 以 看 到 ，ngx_mail_protocol t 接 口 定 义 了 POP3、SMTP、IMAP 等 
应 用 级 别 的 邮件 模块 加 入 到 邮件 框架 时 所 要 实现 的 接口 以 及 需要 遵循 的 
规则 。 





关于 POP3、SMTP、IMAP 模 块 的 定义 ， 这 里 不 再 介绍 ， 读 者 可 以 
自行 查看 Nginx 源 代码 。 在 下 面 的 章节 中 ， 读 者 将 看 到 它们 如 何 结合 邮 
件 框 架 来 实现 邮件 代理 功能 








13.2.3 邮件 框架 的 初始 化 


当 nginx.conf 文 件 中 出 现 mail{} 或 者 imap{} 配 置 项 时 ， 
ngx_mail_module 模 块 就 从 ngx_mail_block 方 法 开始 它 的 初始 化 过 程 (与 
第 10 间 中 的 HTTP 框 染 非常 相似 ) ， 如 图 13-4 所 示 。 










初始 化 每 一 个 邮件 模块 的 


ctx_index 序 号 


分 配 存 放 main 级 别 配 置 项 、svr 
级 别 配 置 项 指针 的 两 个 指针 数组 





调用 所 有 邮件 模块 的 create_main_conf 
方法 创建 存放 main 配 置 项 的 结构 体 


调用 所 ST ‘Teate crv_cont 
夫人 | 克 如 J 页 航 ] 结 


调用 所 有 邮件 模块 的 
init_main_conf 方 法 


调用 所 有 的 Jmerge_ a conf 





构造 监听 端口 re 


的 回调 方 ; 


设置 新 i 


图 13-4 ”邮件 框架 初始 化 的 流程 图 


上 述 过 程 实际 上 就 是 图 10-9 的 简化 版 ， 这 里 不 再 细 说 。 其 中 最 后 一 
步 中 设置 的 TCP 连 接 建 立成 功 后 的 回调 方法 为 
ngx_mail_init_connection， 在 13.3 节 中 会 说 明 此 方法 。 


13.3 ”初始 化 请 求 


Nginx 与 客户 端 建立 TCP 连 接 后 ， 将 会 回调 ngx_mail_init_connection 
方法 开始 初始 化 邮件 协议 ， 这 是 在 处 理 每 个 邮件 请 求 前 必须 要 做 的 工 
作 。 其 中 ， 初 始 化 请 求 时 将 会 创建 类 似 于 HTTP 请 求 中 的 
ngx_http_request_t 这 样 的 核心 结构 体 : ngx_mail_session_t， 在 13.3.1 节 中 
将 会 对 它 进行 介绍 。 另 外 ， 在 13.3.2 节 中 会 说 明 TCP 连 接 建 立成 功 时 
ngx_mail_init_connection 方 法 到 底 做 了 哪些 工作 。 





13.3.1 描述 邮件 请 求 的 ngx_mail_session_t 结 构 体 


ngx_mail_session_t 结 构 体 保存 了 一 个 邮件 请 求 的 生命 周期 里 所 有 可 
能 用 到 的 元 素 ， 如 下 所 示 。 





typedef struct { 
// 目前 未 使 用 


Uint32_t Signature 
// 下 游客 户 端 与 


Nginx 之 间 的 连接 


ngx_connection_t *connection; 
// out 中 可 以 存放 需要 向 下 游客 户 端 发 送 的 内 容 


ngx_str_t out,; 
/* 这 个 缓冲 区 用 于 接收 来 自 客户 端的 请 求 。 这 个 缓冲 区 中 所 使 用 的 内 存 大 小 与 请 求 是 有 关系 的 ， 对 于 


POP3 请 求 固定 为 


128 字 节 ， 对 于 


SMTP 请 求 ， 由 


nginx.Cconf 配 置 文件 中 的 


smtp_client_buffer 配 置 项 决定 ， 对 于 


IMAP 请 求 ， 则 由 


imap_client_buffer 配 置 项 决定 


4 

ngx_buf_t *buffer ， 

/*Ctx 将 指向 一 个 指针 数组 ， 它 的 含义 与 
HTTP 请 求 的 


ngx_http_request_t 结 构 体 中 的 


Ctx 一 致 ， 保 存 着 这 个 请 求 中 各 个 邮件 模块 的 上 下 文 结构 体 指针 


WA 
void **ctx; 
// main 级 别 配置 结构 体 组 成 的 指针 数组 


void **main_conf; 
/*SrV 级 别 配置 结构 体 组 成 的 指针 数组 ， 这 两 个 指针 数组 的 意义 与 第 


10 章 介绍 过 的 


HTTP 框 架 中 的 同名 数组 基本 一 致 ， 只 是 它们 是 用 于 


main{} 配 置 块 下 的 配置 结构 体 


*X 
void **srv_conf; 
// 解析 主机 域名 


ngx_resolver_ctx_t *resolver_ctx; 
/* 请 求 经 过 认证 后 ， 


Nginx 就 开始 代理 客户 端 与 邮件 服务 器 间 的 通信 了 ， 这 时 


proxy 上 下 文 用 于 此 目的 ， 详 见 


13.5 节 


Wp4 
ngx_mail proxy_ctx_t *proxy; 





会 


生成 


/* 表 示 与 邮件 服务 器 交互 时 ， 当 前 处 理 哪 种 状态 。 对 于 


POP3 请 求 来 说 ， 会 隶属 于 


ngx_pop3_state_e 定 义 的 


7 种 状态 ; 对 于 


IMAP 请 求 来 说 ， 会 隶属 于 


ngx_imap_state_e 定 义 的 


8 种 状态 ; 对 于 


SMTP 请 求 来 说 ， 会 隶属 于 


ngx_Ssmtp_state_e 定 义 的 


13 种 状态 


*/ 
ngx_uint_t mail_ state,; 
// 邮件 协议 类 型 目前 仅 有 以 下 


3 于 


// #define NGX_MAIL_POP3_PROTOCOL 
// #define NGX_MAIL_IMAP_PROTOCOL 
// #define NGX_MAIL_ SMTP_PROTOCOL 
unsigned protocol:3; 

// 标志 位 。 


0 
工 
2 


blocked 为 


1 时 表示 当前 的 读 或 写 操作 需要 被 阻塞 


unsigned blocked:1; 
// 标志 位 。 


duit 为 


1 时 表示 请 求 需要 结 


unsigned quit:1; 
// 以 下 


3 个 标志 位 仅 在 解析 具体 的 邮件 协议 时 由 邮件 框架 使 用 


unsigned quoted:1; 

unsigned backslash:1; 
unsigned no_sync_literal:1; 
/* 当 使 用 


SSL 协 议 时 ， 该 标志 位 为 


1 说 明 使 用 


TLS 传 输 层 安全 协议 。 由 于 本 书 不 涉及 


SSL， 故 略 过 


*/ 
unsigned starttls:1; 
/* 表 示 与 认证 服务 器 交互 时 的 记录 认证 方式 。 目 前 有 


6 个 预 设 值 ， 分 别 是 : 


#define NGX_MAIL_AUTH_PLAIN 

#define NGX_MAIL_AUTH_LOGIN 

#define NGX_MAIL_AUTH_LOGIN_USERNAME 
#define NGX_MAIL_AUTH_APOP 

#define NGX_MAIL_AUTH_CRAM_MD5 
#define NGX_MAIL_AUTH_NONE 

unsigned auth_method :3; 








Un 六 局 


4 


1 时 表示 得 知 认证 服务 器 要 求 暂缓 接收 响应 ， 这 时 


Nginx 会 继续 等 待 认证 服务 器 的 后 续 响应 


*% 
unsigned auth wait:1; 
/* 用 于 验证 的 用 户 名 ， 在 与 认证 服务 器 交互 后 会 被 设 为 认证 服务 器 返回 的 响应 中 的 


Auth-User 头 部 


*/ 
ngx_str_t login; 
/* 相 对 于 


login 用 户 名 的 密码 ， 在 与 认证 服务 器 交互 后 会 被 设 为 认证 服务 器 返回 的 响应 中 的 


Auth-Pass 头 部 


4 
ngx_str_t passwd; 
// 作为 


Auth-Salt 验 证 的 信息 


ngx_str_t salt; 
// 以 下 


3 个 成 员 仅 用 于 


IMAP 通 信 


ngx_str_t tag; 
ngx_str_t tagged_ line; 
ngx_str_t text; 

// 当前 连接 上 对 应 的 


Nginx 服 务 器 地 址 


ngx_str_t *addr_text; 
// 主机 地 址 


ngx_str_t host 
// 以 下 


4 个 成 员 仅 用 于 


SMTP 的 通信 


unsigned esmtp:1; 

ngx_str_t smtp_helo; 

ngx_str_t smtp_from; 

ngx_str_t smtp_to; 

/* 在 与 邮件 服务 器 交互 时 ( 即 与 认证 服务 器 交互 之 后 ， 透 传 上 下 游 


TCP 流 之 前 ) ， 


command 表 示 解 析 自 邮件 服务 器 的 消息 类 型 


*/ 
ngx_uint_t command ; 
// args 动 态 数 组 中 会 存放 来 自 下 游客 户 端的 邮件 协议 中 的 参数 


ngx_array_t args,; 
// 当前 请 求 尝试 访问 认证 服务 器 验证 的 次 数 


ngx_uint_t login_attempt,; 
// 以 下 成 员 用 于 解析 


POP3/IMAP/SMTP 等 协议 的 命令 行 


ngx_uint_t state,; 

u_char *cmd_start; 

u_char *arg_start; 

u_char *arg_end; 

ngx_uint_t literal_ len; 
} ngx_mail session t; 





想 要 了 解 邮件 框架 的 处 理 流程 ， 离 不 开 ngx_mail_session_t 结 构 体 的 
帮助 。 如 果 在 阅读 邮件 请 求 的 处 理 过 程 中 过 到 ngx_mail_session_t 结 构 体 


的 成 员 ， 那 么 可 以 返回 本 章 查 询 其 音义 。 


13.3.2 ”初始 化 邮件 请 求 的 流程 


初始 化 邮件 请 求 的 流程 非常 简单 ， 如 图 13-5 所 示 。 

















为 请 求 创建 
session_t 结 构 体 


nex_mail session_t 4i 








根据 TCP 连 接 上 上 本 机 半日 此 到 对 应 的 


se srver 本 置 块 局 









攻 文 置 ngx _mall send 


为 向 客户 端 发 送 响 应 的 方法 


根据 server 配 置 块 里 设置 的 协议 调用 相应 
邮件 模块 的 init_session 方 法 





图 13-5 ”初始 化 邮件 请 求 的 流程 


实际 上 ， 初 始 化 流程 中 最 关键 的 一 步 就 是 调用 POP3、SMTP、 
IMAP 等 具体 邮件 模块 实现 ngx_mail_protocol_t 接 口中 的 init_session 方 
法 ， 这 些 邮 件 模块 会 根据 自己 处 理 的 协议 类 型 初始 化 ngx_mail_session_t 
结构 体 。 在 POP3、SMTP、IMAP 邮 件 模块 内 实现 的 init_session 方 法 中 ， 
都 会 设置 由 各 自 实现 的 init_protocol 方 法 接收 、 解 析 客 户 端 请 求 ， 这 里 不 
再 详细 说 明 每 个 邮件 模块 是 如 何 实现 init_session 方 法 的 。 








13.4 接收 并 解析 客户 站 请 求 


无 论 是 POP3、SMTP 还 是 IMAP 邮 件 模块 ， 在 处 理 客户 端的 请 求 
时 ， 都 是 使 用 ngx_mail_protocol_t 接 口中 的 init_protocol 方 法 完成 的 ， 它 
们 的 流程 十 分 相似 : 首先 反复 地 接收 客户 端 请 求 ， 并 使 用 状态 机 解析 是 
否 收 到 足够 的 信息 ， 直 到 接收 了 完整 的 信息 后 才 会 跳 到 下 一 个 邮件 认证 
阶段 执行 (通过 调用 ngx_mail_auth 方 法 ) 。 


使 用 状态 机 解析 来 自 客户 端的 TCP 流 的 方法 其 实 束 是 通过 
ngx_mail_protocol_t 接 口中 的 parse_command 方 法 来 完成 的 ，POP3、 
SMTP、IMAP 邮 件 模 块 实现 的 parse_command 方 法 都 在 ngx_mail_parser.c 
源 文件 中 。 由 于 本 章 不 涉及 邮件 协议 的 细节 ， 这 里 不 再 一 一 说 明 。 


13.5 邮件 认证 


邮件 认证 工作 由 ngx_mail_auth 方 法 执行 。 邮 件 认证 服务 器 的 地 址 在 
nginx.conf 文 件 的 auth_http 配 置 项 中 设置 (参见 13.1 节 〉 ， 这 一 认证 流程 
相对 独立 ， 其 认证 功能 是 由 ngx_mail_auth_http_module 邮 件 模块 提供 
的 。 在 与 认证 邮件 服务 器 打交道 的 过 程 中 ， 结 构 体 
ngx_mail_auth_http_ctx_t 会 贯穿 其 始终 ， 它 保存 有 连接 、 请 求 内 容 、 响 
应 内 容 、 解 析 状态 等 必要 的 成 员 ， 在 认证 完 邮件 后 将 会 通过 销毁 内 存 池 
来 销毁 这 个 结构 体 。 





13.5.1 ngx_mail_auth_http_ctx_t 结 构 体 





ngx_mail_auth_http_ctx_t 结 构 体 是 在 其 成 员 pool 指 癌 的 内 存 池 中 分 
配 的 ， 它 的 地 址 实际 上 保存 在 ngx_mail_session_t 的 ctx 指 针 数 组 中 (实际 
上 上， 在 ngx_mail_auth_http_module 模 块 ctx_index 成 员 指 出 的 序号 对 应 的 
ctx 数 组 元 素 中 ， 相 当 于 该 模块 的 上 下 文 结构 体 ) 。 邮 件 框架 提供 给 各 
个 邮件 模块 的 两 个 方法 用 于 在 ctx 指 针 数 组 中 设置 、 取 出 上 下 文 结构 体 
的 地 址 ， 如 下 所 示 。 





#define ngx_mail get module ctx(s, module) (Ss)->ctx[module.ctx_index] 
#define ngx_mail set_ ctx(s, c, module) s->ctx[module.ctx_index] = c; 








其 实际 用 法 跟 HTTP 框 架 中 的 ngx_http_set_ctx 方 法 非常 相似 。 例 


如 ， 假 设 指 针 ctx 就 是 刚刚 分 配 的 ngx_mail_auth_http_ctx_t 结 构 体 地 址 ， 
而 s 是 每 个 请 求 的 ngx_mail_session_t 结 构 体 指针 ， 那 么 可 以 这 样 设置 到 
请 求 的 ctx 数 组 中 : 








ngx_mail set_ ctx(s, ctx, ngx_mail auth_ http_module); 








下 面 详细 介绍 ngx_mail_auth_http_ctx_t 结 构 体 中 的 每 个 成 员 。 





typedef struct ngx _ mail auth_ http ctx _s ngx_ mail auth_http_ctx_t; 
// 解析 认证 服务 器 





HTTP 响 应 的 方法 指针 


typedef void (*ngx_mail auth_http_handler_pt) (ngx_mail session t *s, ngx_mail auth_ 
struct ngx_mail auth http_ctx_s { 
/* request 缓 冲 区 保存 着 发 往 认证 服务 器 的 请 求 。 它 是 根据 解析 客户 端 请 求 得 到 的 








ngx_mai]l_session tt， 使 用 





ngx_mail_auth_http_create_redquest 方 法 构造 出 的 内 存 缓 冲 区 。 这 里 的 请 求 是 一 种 类 


HTTP 的 请 求 


2 
ngx_buf t *redquest 
// 保存 认证 服务 器 返回 的 类 


HTTP 响 应 的 缓冲 区 。 缓 冲 区 指向 的 内 存 大 小 国定 为 


1KB 
ngx_buf_t *response; 
// Nginx 与 认证 服务 器 间 的 连接 


ngx_peer_connection_t peer; 
/* 解 析 来 自 认 证 服务 器 类 


HTTP 的 响应 行 、 头 部 的 方法 (参见 图 


13-6) ， 默 认为 


ngx_mail auth_http_ignore_status_line 方 法 





*/ 
ngx_mail auth_http_handler_pt handler; 
/* 在 使 用 状态 机 解析 认证 服务 器 返回 的 类 





HTTP 响 应 时 ， 使 用 


State 表 示 解 析 状 态 


“7 
ngx_uint_t state; 
/* ngx_mail auth_http_parse_header_line 方 法 负责 解析 认证 服务 器 发 来 的 响应 中 类 





HTTP 的 头 部 ， 以 下 


4 个 成 员 用 于 解析 响应 头 部 


*/ 
u_char *header_name_start,; 
u_char *header_name_end; 
u_char *header_start,; 
u_char *header_end; 
// 认证 服务 器 返回 的 


Auth-Server 头 部 


ngx_str_t addr; 
// 认证 服务 器 返回 的 


Auth-Port 头 部 


ngx_str_t port; 
// 错误 信息 


ngx_str_t err,; 
// 错误 信息 构成 的 字符 串 


ngx_str_t errmsg, 
/* 错 误 码 构成 的 字符 串 。 如 果 认证 服务 器 返回 的 头 部 里 有 


Auth-Error-Code， 那 么 将 会 设置 到 


errcode 中 。 


errmsg 和 


errcode 在 发 生 错误 时 会 直接 将 其 作为 响应 发 给 客户 端 


*/ 
ngx_str_t errcode 
/* 认 证 服务 器 返回 


Auth-Wait 头 部 时 带 的 时 间 玲 将 会 被 设 到 


Sleep 成 员 中 ， 而 


Nginx 等 待 的 时 间 也 将 由 


Sleep 维 护 ， 当 


Sleep 降 为 


0 时 将 会 设 轩 


quit 标 志 位 为 


1 ， 表 示 请 求 非 正常 结束 ， 把 错误 码 返回 给 用 户 


time_t sleep; 
// 用 于 邮件 认证 的 独立 内 存 池 ， 它 的 初始 大 小 为 


2KB 
ngx_pool_t *pool; 





13.5.2 与 认证 服务 器 建立 连接 


图 13-6 中 摘 述 了 ngx_mail_auth 方 法 所 做 的 工作 ， 包 括 初 始 化 与 认证 
服务 器 交互 之 前 的 工作 、 发 起 TCP 连 接 等 。 


图 13-6 中 设置 了 Nginx 与 下 游客 户 端 则 TCP 连 接 上 的 读 事件 处 理 方法 
为 ngx_mail_auth_http_block_read， 这 个 方法 所 做 的 唯一 工作 其 实 就 是 再 
次 调用 ngx_handle_read_event 方 法 把 读 事 件 义 添加 到 epoll 中 ， 这 意味 着 
它 不 会 读 取 任何 客户 端 发 来 的 请 求 ， 但 同时 保持 着 读 事件 被 epol 监控 。 
在 与 认证 服务 器 间 TCP 连 接 上 ， 写 事件 的 处 理 方法 为 
ngx_mail_auth_http_write_handler， 它 负责 把 构造 出 的 request 绥 冲 区 中 的 
请 求 发 送 给 认证 服务 器 ; 读 事 件 的 处 理 方法 为 
ngx_mail_auth_http_read_handler， 这 个 方法 在 接收 到 认证 服务 器 的 啊 应 
后 会 调用 ngx_mail_auth_http_ignore_status_line 方 法 首先 解析 HTTP 响 应 











行 。 





人 户 端 请 求 的 buffer 


区 清空 









login_attempt 表 示 的 认证 
尝试 次 数 加 1 





分 配 2KB 的 内 存 池 用 于 访问 认证 服务 器 ， 
认证 时 使 用 的 内 存 都 由 该 内 存 池 中 分 配 


建立 ngx_mailauth_http_ctx_t 


结构 体 


在 缓冲 区 request 
上 构造 发 往 认 证 服务 器 的 请 求 








向 认证 服务 器 发 起 连接 ， 
同时 把 套 接 字 加 入 epol 和 定时 器 中 





设置 下 游 连接 上 的 读 
事件 处 理 方法 


设置 二 认证 服务 器 间 连 接 的 
读 - 


设置 与 认证 服务 器 间 连 接 的 
写 事 件 处 理 方 法 
[检查 TCP 连接 是 否 建 立成 功 ] 








[与 认证 服务 器 间 连 接 建 立成 功 ] 









[TCP 连接 暂 未 建立 成 功 ] 
调用 ngx mailauth http_write_handler 


方法 向 认证 服务 器 发 送 请 求 


图 13-6 ”启动 邮件 认证 、 向 认证 服务 器 发 起 连接 的 流程 


13.5.3 ”发 送 请 求 到 认证 服务 右 


ngx_mail_auth_http_write_handler 会 发 送 request 绥 冲 区 中 的 请 求 到 认 
证 服务 器 ， 它 的 代码 非常 简单 ， 如 下 所 示 。 





static void ngx_mail auth http write handler(ngx_event_t *wev) 


{ 





ssize _t n, size,; 
ngx_connection _t *c; 

ngx_mail]_ session_t *s,; 

ngx_mail] auth_http_ctx_t *ctx; 
ngx_mail auth_http_conf_t *ahcf; 
// 写 事件 上 的 








data 成 员 存 放 的 是 


Nginx 与 认证 服务 器 间 的 


TCP 连 接 


C = wev->data; 
// 连接 的 


date 成 员 指 向 


ngx_mail_session_t 结 构 体 


s = c->data,; 
// 获得 描述 认证 过 程 的 


ngx_mail_auth_http_ctx_t 结 构 体 





ctx = ngx_mail get module ctx(s, ngx_mail auth_http_module); 
/如 果 向 认证 服务 器 发 送 请 求 超时 ， 则 关闭 连接 、 销 毁 内 存 池 ， 并 向 客户 端 发 送 错误 响应 








if (wev->timedout) { 
ngx_close_connection(c); 
ngx_destroy_pool(ctx->pool); 
ngx_mail session_internal server_error(s); 
return; 


/计算 还 剩 下 多 少 字 节 的 请 求 没有 发 送出 去 ， 
pos 和 
last 之 间 的 内 容 就 是 待 发 送 的 请 求 
*/ 


size = ctx->request->last - ctx->request->pos ; 
// 向 认证 服务 器 发 送 请 求 


n = ngx_send(c, ctx->request->pos, size); 
// 如 果 发 送 失败 ， 则 关闭 连接 、 销 毁 内 存 池 ， 并 向 客户 端 发 送 错误 响应 


if (n == NGX_ERROR) { 
ngx_close_connection(c); 
ngx_destroy_pool(ctx->pool); 
ngx_mail session_internal server_error(s); 
return; 


} 
// 如 果 成 功 发 送 了 请 求 


if (n > 0) { 
// 更 新 


request 缓 冲 区 


ctx->request->pos += nN; 
/*Size 表 示 还 需要 发 送 的 请 求 长 度 ， 


n 表 示 本 次 发 送 的 请 求 长 度 ， 当 它们 相等 时 ， 意 味 着 已 经 将 全 部 响应 发 送 到 认证 服务 器 


*/ 
if (n == size) { 
/* 将 


Nginx 与 认证 服务 器 间 连 接 的 写 事件 回调 方法 设 为 任何 事情 都 不 做 的 


ngx_mail_auth_http_dummy_handler 方 法 





4 
wev->handler = ngx_mail auth_http_dummy_handler; 
/* 由 于 不 再 需要 发 送 请 求 ， 所 以 不 需要 再 监控 发 送 是 否 超时 。 如 果 写 事件 还 在 定时 器 中 ， 则 移 除 








If (wev->timer_set) { 
ngx_del timer (wev); 





} 
// 将 写 事件 添加 到 


epoll 中 


if (ngx_handle write event(wev, 0) != NGX OK) { 
ngx_close_connection(c); 
ngx_destroy_pool(ctx->pool); 
ngx_mail_session_internal_ server_error(s); 





return; 


} 


} 
// 如 果 定时 器 中 没有 写 事件 ， 那 么 把 它 添加 到 定时 器 中 监控 发 送 请 求 是 否 超时 


if (!wev->timer_set) { 
ahcf = ngx_mail get module_ srv_conf(s, ngx_mail auth_http_module); 
ngx_add_timer (wev, ahcf->timeout); 











13.5.4 接收 并 解析 响应 





接收 并 解析 认证 服务 器 啊 应 的 方法 是 
ngx_mail_auth_http_read_handler， 访 方法 要 同时 负责 解析 响应 行 和 


HTTP 头 部 ， 较 为 复杂 ， 图 13-7 描 述 了 其 中 的 主要 流程 。 


图 13-6 中 所 描述 的 流程 包括 两 个 阶段 ， 首 先 接收 到 完整 的 HITP 啊 
应 行 ， 其 次 接收 到 完整 的 HTTP 啊 应 头 部 。 这 两 个 阶段 都 并 非 一 次 调度 


就 一 定 可 以 完成 的 ， 因 此 ， 当 没有 收 到 足够 的 TCP 流 供 状态 机 解析 时 ， 
都 会 期 待 epoll 下 一 次 重新 调度 图 13-6 中 的 流程 。 在 全 部 解析 完 响应 后 ， 
将 可 以 得 知 认证 是 否 通过 ， 如 果 请 求 合 法 ， 那 么 可 以 从 HTTP 响应 头 部 
中 得 到 上 游 邮 件 服 务 器 的 地 址 ， 接 着 通过 调用 ngx_mail_proxy_init 方 法 
进入 与 邮件 服务 器 交互 的 阶段 。 


13.6 ”与 上 游 邮 件 服 务 器 间 的 认证 交互 


对 于 POP3、SMITP、IMAP 来 次， 客户 端 与 邮件 服务 器 之 间 最 初 的 
交互 目的 都 不 太 相 同 。 例 如 ， 对 于 POP3 和 IMAP 来 说 ， 与 邮件 服务 器 间 
的 TCP 连 接 一 旦 建立 成 功 ， 邮 件 服 务 器 会 发 送 一 个 欢迎 信息 ， 接 着 客户 
端 〈 此 时 ，Nginx 是 邮件 服务 器 的 客户 端 ) 发 送 用 户 名 ， 在 邮件 服务 器 
返回 成 功 后 再 发 送 密码 ， 等 邮件 服务 器 验证 通过 后 ， 才 会 进入 到 邮件 处 
理 阶 段 ， 对 于 Nginx 这 个 邮件 代理 服务 器 来 说 ， 就 是 进入 到 纯粹 地 透 传 
Nginx 与 上 、 下 游 间 两 个 TCP 连 接 之 间 的 数据 流 《〈 见 13.7 节 ) 。 但 对 于 
SMTP 来 说 ， 这 个 交互 过 程 又 有 所 不 同 ， 进 入 邮件 处 理 阶段 前 需要 交互 
传输 邮件 来 源 地 址 、 邮 件 目标 地 址 〈 也 就 是 From...To...) 等 信息 。 


[检查 读 事 件 上 的 timeout 标 志 位 是 否 超 时 ] 





[接收 未 超时 , 再 检查 response 是 否 已 分 配 内 存 用 于 接收 响应 ] 










[response 缓冲 区 已 存在 ] 


[未 分 配 用 于 接收 响应 的 内 存 缓冲 区 ] 









在 response 绥 冲 区 上 分 配 1KB 
的 内 存 用 于 接收 认证 服务 器 响应 





[接收 响应 超时 ] 


使 用 recv 方 法 在 reponse 
上 接收 响应 


[检查 recv 方 法 的 返回 值 ] 








[接收 到 响应 ] [失败 或 者 连接 意外 关闭 ] 













调用 ngx_mail_auth_http_ignore_status_line 
ey 未 解析 过 响应 行 ， 方法 解析 响应 行 
次 应 解析 HTTP 头 部 ] [检查 是 否 接 收 到 完整 的 响应 行 ] 






[解析 响应 行 出 错 ] 


[解析 到 完整 响应 行 , 开始 解析 HTTP 头 部 ] 


设置 ngx_mail_auth_http_process_headers 


为 解析 HTTP 头 部 的 方法 





需 型 合 汪 大 询 证 继 融 搂 收 | [检查 是 否 接收 到 完整 的 HTTP 头 部 ] 






关闭 与 认证 服务 器 
调用 ngxmail_auth_http_process_headers 间 的 连接 
解析 头 次 


[检查 是 否 接收 到 完整 HTTP 头 部 ] 
[解析 头 部 出 销 ] 


销毁 用 于 认证 邮件 的 
内 存 池 

向 客户 端 

发 送 错误 











[解析 到 完整 头 部 , 认证 成 功 ] 


[未 接收 完 头 部 ， 
= 二 符 下 一 次 调度 ] 












关闭 连接 ， 销 毁 内 存 池 ， 
进入 下 一 阶段 


图 13-7 接收 并 解析 来 自 认证 服务 器 的 响应 


无 论 如何 ，Nginx 作 为 邮件 代理 服务 器 在 接收 到 客户 端的 请 求 ， 并 
且 收 集 到 足够 进行 认证 的 信息 后 ， 将 会 由 Nginx 与 上 游 的 邮件 服务 器 进 
行 独立 的 交互， 直到 邮件 服务 器 认为 可 以 进入 到 处 理 阶 段 时 ， 才 会 开始 
透 传 协议 。 这 一 阶段 将 围绕 着 ngx_mail_proxy_ctx_t 结 构 体 中 的 成 员 进 
行 。 下 面 以 POP3 协 议 为 例 简 单 地 说 明 Nginx 是 如 何 与 邮件 服务 器 交互 
的 。 








13.6.1 ngx_mail_proxy_ctx_t 结 构 体 


ngx_mail_session_t 结 构 体 中 的 proxy 成 员 指 向 ngx_mail_proxy_ctx_t 
结构 体 ， 该 结构 体 含 有 Nginx 与 上 游 间 的 连接 upstream， 以 及 与 上 游 通信 
时 接收 上 游 TCP 消 息 的 缓冲 区 ， 如 下 所 示 。 





typedef struct { 
// 与 上 游 邮 件 服务 器 间 的 连接 


ngx_peer_connection_t upstreanm,; 
/* 用 于 缓存 上 、 下 游 间 


TCP 消 息 的 内 存 缓冲 区 ， 内 存 大 小 由 
nginx.conf 文 件 中 的 


proxy_buffer 配 置 项 决定 


ngx_buf t *buffer 
} ngx_mail_proxy_ctx_t; 





| ————= | 


人 @@ 注意 proxy 成 员 最 初 也 是 NULL 空 指针 ， 直 到 调用 


ngx_mail_proxy_init 方 法 后 才 会 为 proxy 指 针 分 配 内 存 。 
13.6.2” 问 上 游 邮 件 服务 器 发 起 连接 


根据 ngx_mail_proxy_init 方 法 可 以 启动 Nginx 与 上 游 邮 件 服 务 器 间 的 
交互 ， 下 面 看 一 下 该 方法 主要 做 了 哪些 工作 。 





void ngx_mail proxy_init(ngx mail session t *s, ngx_addr_t *peer) 


// 创建 


ngx_mail_proxy_ctx 七 结构 体 





ngx_mail_proxy_ctx_t *p = ngx_pcalloc( s->connection->pool, sizeof(ngx_mail_pro) 
if (p == NULL) { 

ngx_mail session_internal server_error(s); 

return; 





} 


// 注意 ,之 前 的 
proxy 成 员 指 向 的 是 


NULL 空 指针 


Ss->proxy = p;, 


// 向 上 游 的 邮件 服务 器 发 起 无 阻塞 的 


TCP 连 接 


ngx_int_t rc = ngx_event_connect_peer(&p->upstream); 


“需要 监控 接收 邮件 服务 器 的 响应 是 否 超时 ， 于 是 把 与 上 游 间 连接 的 读 事件 添加 到 定时 器 中 





*/ 
ngx_add_timer(p->upstream.connection->read, cscf->timeout); 
// 设置 连接 的 

data 成 员 指 向 


ngx_mail_session_t 结 构 体 


p->upstream.connection->data = s; 
/* 设 置 


Nginx 与 客户 端 间 连 接 读 事件 的 回调 方法 为 不 会 读 取 内 容 的 


ngx_mail_proxy_block_read 方 法 ， 因 为 当前 阶段 








Nginx 不 会 与 客户 端 交 互 


大 





s->connection->read->handler = ngx_mail proxy_block_read; 
/* 设 置 





Nginx 与 上 游 间 的 连接 写 事件 回调 方法 为 什么 事 都 不 做 的 


ngx_mail_proxy_dummy_handler 方 法 ， 这 意味 着 接 下 来 向 上 游 发 送 





TCP 流 时 ， 将 不 再 通过 


epo1l1 这 个 事件 框架 来 调度 ， 下 一 节 将 看 到 实际 的 用 法 


4 
p->upstream.connection->write->handler = ngx_mail proxy_dummy_handler; 
/* 建 立 





Nginx 与 邮件 服务 器 间 的 内 存 缓 冲 区 ， 缓冲 区 大 小 由 


nginx.conf 文 件 中 的 


proxy_buffer 配 置 项 决定 


*/ 
S->proxy->buffer = ngx_create_ temp_buf(s->connection->pool, 
pcf->buffer_size); 
// 注意 ,设置 


Out 为 空 ， 表 示 将 不 会 再 通过 


OUt 向 客户 端 发 送 响应 


s->out.len = 0; 
// 根据 用 户 请 求 的 协议 设置 实际 的 邮件 认证 方法 


Switch (s->protocol) { 
case NGX_MAIL_POP3_PROTOCOL : 
// 设置 


POP3 协 议 进 行 邮件 交互 认证 的 方法 


p->upstream.connection->read->handler = ngx_mail proxy_pop3_handler; 
s->mail_state = ngx_pop3_start,; 
break; 
case NGX_MAIL_IMAP_PROTOCOL : 
// 设置 





IMAP 进 行 邮 件 交 互 认 证 的 方法 


p->upstream.connection->read->handler = ngx_mail proxy_imap_handler; 
s->mail_state = ngx_imap_start,; 
break; 
default: /* NGX_MAIL_SMTP_PROTOCOL */ 
// 设置 





SMTP 进 行 邮件 交互 认证 的 方法 


p->upstream.connection->read->handler = ngx_mail proxy_smtp_handler; 
s->mail_state = ngx_smtp_start,; 
break; 





可 以 看 到 ， 其 中 最 重要 的 工作 在 于 分 配 了 ngx_mail_proxy_ctx_t 结 构 
体 ， 并 为 成 员 buffer 分 配 了 内 存 缓冲 区 ， 用 于 接收 上 游 的 TCP 消 息 ， 同 
时 使 用 upstream 与 上 游 建立 了 TCP 连 接 ， 最 后 针对 不 同 的 邮件 协议 分 别 
设置 了 ngx_mail_proxy_pop3_handler、ngx_mail_proxy_imap_handler 或 
者 ngx_mail proxy_smtp_handler 方 法 ， 用 于 Nginx 与 上 游 邮 件 服务 器 间 的 
Sa 








13.6.3 与 邮件 服务 器 认证 交互 的 过 程 





由 于 每 种 协议 的 交互 过 程 都 不 相同 ， 因 此 下 面 仅 以 POP3 协 议 为 例 
简单 地 说 明 这 一 过 程 是 如 何 实现 的 ， 如 下 所 示 。 








static voidngx_mail proxy_pop3_handler(ngx_event t *rev) 





u_char *p; 

ngx_int_t rc; 

ngx_connection _t *c; 

ngx_mail]_ session_t *s,; 

ngx_mail]_ proxy_conf_t *pcf; 

// line 将 会 保存 发 往 上 游 邮 件 服务 器 的 消息 





ngx_str_t line; 
// 获取 


Nginx 与 上 游 间 的 连接 


C = rev->data; 


// 获得 


ngx_mail_session 七 结构 体 


S = c->data; 


// 如 果 读 取 上 游 邮件 服务 器 响应 超时 ， 则 向 客户 端 发 送 错误 响应 


if (rev->timedout) { 
c->timedout = 1; 
ngx_mail_proxy_internal_ server_error(s); 
return; 


} 
// 读 取 上 游 邮件 服务 器 发 来 的 响应 到 


buffer 缓 冲 区 中 


rc = ngx_mail_ proxy_read_response(s, 0); 
// 还 需要 继续 接收 邮件 服务 器 的 消息 ， 期 待 下 一 次 的 调度 





if (rc == NGX_AGAIN) { 
return; 


// 消息 不 合法 ， 或 者 邮件 服务 器 没有 验证 通过 ， 则 返回 错误 给 客户 端 


if (rc == NGX_ERROR) { 
ngx_mail_proxy_upstream_error(s); 
return; 

} 

switch (s->mail state) { 

case ngx_pop3_start: 
// 构造 发 送 给 邮件 服务 器 的 用 户 信 息 


line.len = sizeof("USER ") - 1 + Ss->login.len + 2; 
line.data = ngx_pnalloc(c->pool, line.1len); 
if (line.data == NULL) { 
ngx_mail_proxy_internal_ server_error(s); 
return; 


ngx_cpymem(line.data, "USER ", sizeof("USER ") - 1); 
ngx_cpymem(p, Ss->login.data, s->login.1en); 
pt++ = CR; *p = LF,; 
s->mail_state = ngx_pop3_user; 
break; 
case ngx_pop3_user: 
// 构造 发 送 给 邮件 服务 器 的 密码 信息 


i 
lll 


line.len = sizeof("PASS ") - 1 + Ss->passwd.]len + 2; 
line.data = ngx_pnalloc(c->pool, line.1len); 
if (line.data == NULL) { 
ngx_mail_proxy_internal_ server_error(s); 
return; 


"EY 


= ngx_cpymem(line.data, "PASS ", sizeof("PASS ") - 1); 


p = ngx_cpymem(p, 
“p++ = CR; *p = LF; 
s->mail_ state = ngx_pop3_passwd; 


break; 


case ngx_pop3_passwd: 
/* 在 收 到 服务 器 返回 的 密码 验证 通过 信息 后 ， 将 


Nginx 与 下 游客 户 端 间 、 


Nginx 与 上 游 邮件 服务 器 间 的 


TCP 连 接 上 读 


/ 写 事件 的 回调 方法 都 设置 为 


s->passwd.data, s->passwd.1en); 


ngx_mail_proxy_handler 方 法 (参见 


13.7 节 ) 


s->connection->read->handler = ngx_mail proxy_handler; 
s->connection->write->handler = ngx_mail_ proxy_handler; 
rev->handler = ngx_mail proxy_handler; 
c->write->handler 


// 进入 透 传 上 、 下 游 


TCP 阶 段 


= ngx_mail proxy_handler; 


ngx_mail proxy_handler(s->connection->write); 


return; 
defauilt: 


#if (NGX_SUPPRESS_WARN) 
ngx_str_null(&line); 


#endif 
break; 


} 
/* 向 上 游 的 邮件 服务 器 发 送 验 证 信息 。 注 意 ， 这 里 向 邮件 服务 器 发 送 


TCP 流 与 本 书 的 其 他 章节 都 不 相同 ， 它 不 再 通过 


ep011 检 测 到 


TCP 连 接 上 出 现 可 写 导 





了 件 而 触发 。 和 习 





了 实 上 ， 它 是 由 连接 上 出 现 的 可 读 事 件 触 发 的 ， 因 为 读 取 到 了 邮件 服务 器 的 消息 


TCP 消 息 包 都 非常 短小 


*/ 
If (c->send(c, line.data, line.len) < (ssize t) line.len) { 
ngx_mail_proxy_internal_server_error(s); 
return; 
} 
// 清空 
buffer 缓 冲 区 
S->proxy->buffer->pos = s->proxy->buffer->start; 
s->proxy->buffer->last = s->proxy->buffer->start; 
} 





一 旦 收 到 用 户 名 、 密 码 验证 通过 的 消息 ， 就 会 由 
ngx_mail_proxy_handler 方 法 进入 透 传 上 、 下 游 TCP 流 的 阶段 。 


13.7 透 传 上 游 邮 件 服务 器 与 客户 端 间 的 流 





ngx_mail_proxy_handler 方 法 同时 负责 处 理 上 、 下 游 间 的 四 个 事件 
(两 个 读 事件 、 两 个 写 事件 ) 。 该 方法 将 完全 实现 上 、 下 游 邮 件 协 议 之 
间 的 透 传 ， 本 节 将 通过 直接 研究 这 个 方法 来 看 看 如 何 用 固定 大 小 的 缓存 
实现 透 传 功能 (有 些 类 似 于 upstream 机 制 转发 响应 时 仅 用 了 固定 缓存 的 
模式 ， 但 upstream 机 制 只 是 单 向 的 转发 ， 而 透 传 则 是 双向 的 转发 〉。 





下 面 先 来 介绍 双向 转发 TCP 流 时 将 会 用 到 的 两 个 缓冲 区 : 
ngx_mail_session_t 中 的 buffer 绥 冲 区 用 于 转发 下 游客 户 端 的 消息 给 上 游 
的 邮件 服务 器 ， 而 ngx_mail_proxy_ctx_t 中 的 buffer 绥 冲 区 则 用 于 转发 上 
游 邮件 服务 器 的 消息 给 下 游 的 客户 端 。 在 这 两 个 ngx_buf t 类 型 的 缓冲 区 
中 ，pos 指 针 指 向 待 转发 消息 的 起 始 地 址 ， 而 last 指 针 指 向 最 后 一 次 接收 
到 的 消息 的 末尾 。 当 pos 等 于 last 时 ， 意 味 着 全 部 缓存 消息 都 转发 完了 ， 
这 时 会 把 pos 和 1last 都 指向 缓冲 区 的 首部 start 指 针 ， 相 当 于 清空 缓冲 区 以 
便 再 次 复 用 完整 的 缓冲 区 。 相 关 代码 如 下 所 示 。 

















static void ngx_mail_proxy_handler(ngx_event_t *ev) 


// 当前 的 动作 ， 用 于 记录 日 志 


char *action, *recv_action, *send_action,; 
/*Size 交 量具 有 两 种 含义 : 在 读 取 消息 时 ， 


Size 表 示 


recVv 方 法 中 空闲 缓冲 区 的 大 小 ， 在 发 送 消息 时 ， 表 示 将 要 发 送 的 消息 长 度 


size_t size; 
// send 或 者 
recv 方 法 的 返回 值 


ssize_t n; 
// b 表 示 用 于 接收 


TCP 消 息 的 缓冲 区 ， 或 者 指向 用 于 发 送 消 息 的 缓冲 区 


ngx_buf_t *b; 
// do_write 标 志 位 决定 本 次 到 底 是 发 送 还 是 接收 


TCP 消 息 


ngx_uint_t do write; 
/* 每 次 中 传 


TCP， 上 、 下 游 的 客户 端 与 邮件 服务 器 之 间 必 然 有 一 个 负责 提供 消息 ， 另 一 个 负责 接收 


Nginx 转 发 的 消息 。 


SrCc 用 来 表示 


Nginx 与 提供 消息 一 方 之 间 的 连接 ， 而 


dst 表 示 


Nginx 与 接收 消息 一 方 之 间 的 连接 


xs 
ngx_connection _t *c, *src, *dst; 
ngx_mail]_session_t *s,; 
ngx_mail proxy_conf_t *pcf; 
/* 注 意 ， 事 件 








eV 既 可 能 属于 


Nginx 与 下 游 间 的 连接 ， 也 有 可 能 属于 
Nginx 与 上 游 间 的 连接 ， 此 时 无 法 判断 连接 
C 究 竟 是 来 自 于 上 游 还 是 下 游 


*/ 
C = ev->data,; 
/* 无 论 是 在 上 游 连接 还 是 下 游 连 接 上 ， 


ngx_connection 七 结构 体 的 
data 成 员 都 将 指向 
ngx_mail_session tt 结构 体 


*/ 
S = c->data; 
// 无 论 上 、 下 游 ， 只 要 接收 或 者 发 送 消息 出 现 了 超时 ， 都 需要 终止 透 传 操作 


if (ev->timedout) { 


// ngx_mail proxy_close_session 方 法 会 同时 关闭 上 、 下 游 的 








TCP 连 接 
ngx_mail proxy_close_ session(s); 
return; 
/* 注 意 ， 


ngx_mail_session_t 结 构 体 中 的 


connection 成 员 一 定 指向 


Nginx 与 下 游客 户 端 间 的 


TCP 连 接 


*/ 
If (c == s->connection) { 











// 以 下 分 支 意味 着 收 到 了 下 游 连接 上 的 事件 (无 论 是 可 读 事件 还 是 可 写 事件 ) 


if (ev->write) { 
/* 当 下 游 可 写 事件 被 触发 时 ， 意 味 着 本 次 


Nginx 将 负责 把 接收 自 上 游 的 缓存 消息 发 送 给 下 游 


yA 
recv_action 
send_action 
// 设 


"proxying and reading from upstream"; 
"proxying and sending to client",; 


SrC 来 源 连 接 为 上 游 连接 


src = s->proxy->upstream.connection; 
// 设 


dst 目 标 连 接 为 下 游 连接 


dst = c; 
// 设置 用 于 向 下 游 发 送 的 消息 缓冲 区 


b = s->proxy->buffer; 
} else { 
/* 当 下 游 可 读 事件 被 触发 时 ， 意 味 着 本 次 


Nginx 将 负责 先 读 取 下 游 的 响应 到 缓存 中 ， 为 下 一 步 转发 绘 上游 做 准备 


7 
recv_action 
send_action 
// 设 


"proxying and reading from client"; 
"proxying and sending to upstream"; 


SrC 来 源 连 接 为 下 游 连 接 
src = Cc; 
// 设 


dst 目 标 连接 为 上 游 连接 


dst = s->proxy->upstream.connection; 


// 设置 用 于 接收 下 游 消 息 的 缓冲 区 


b = S->buffer ， 


} 
} else { 
// 以 下 分 支 意 味 着 收 到 了 上 游 连接 上 的 事件 





if (ev->write) { 
/* 当 上 游 可 写 事件 被 触发 时 ， 意 味 着 本 次 





Nginx 将 负责 把 接收 自 下 游 的 缓存 消息 发 送 给 上 游 


*/ 
recv_action 
send_action 
// 设 


"proxying and reading from client"; 
"proxying and sending to upstream"; 


SrC 来 源 连 接 为 下 游 连 接 


src = s->connection,; 
// 设 


dst 来 源 连 接 为 上 游 连 接 


dst = c; 
// 设置 用 于 向 上 游 发 送 的 消息 缓冲 区 


b = S->buffer ， 
} else { 
/* 当 上 游 可 读 事件 被 触发 时 ， 意 味 着 本 次 





Nginx 将 负责 接收 上 游 的 消息 到 缓存 中 ， 为 下 一 步 把 这 个 消息 转发 给 下 游 做 准备 


*/ 
recv_action = "proxying and reading from upstream"; 
send_action = "proxying and sending to client",; 
// 设 
SrCc 来 源 连接 为 上 游 连接 
src = Cc; 


dst 来 源 连 接 为 下 游 连接 


dst = S->connection 
// 设置 用 于 接收 上 游 消息 的 缓冲 区 


b = S->proxy->buffer 


} 
// 当前 触发 事件 的 





Write 标志 位 将 决定 


do_write 本 次 是 发 送 消息 还 是 接收 消息 


do write = ev->write 1 : 0; 
/* 进 入 向 


dst 连 接 发 送 消 息 或 者 由 
SrC 连 接 上 接收 消息 的 循环 ， 直 到 套 接 字 上 和 暂 无 可 读 或 可 写 事件 时 才 退 出 


*/ 
for ( ;; ) 
If (do write) { 
// 如 果 本 次 将 发 送 


TCP 消 息 ， 那 么 首先 计算 出 要 发 送 的 消息 长 度 


= b->last - b->pos,; 
// 检查 需要 发 送 的 消息 长 度 


Size 是 否 大 于 


9， 以 及 目标 连接 当前 是 否 可 生 


if (size && dst->write->ready) { 
c->1og->action = send_action; 
// 调用 


Send 方 法 向 


dst 目 标 连接 上 发 送 


TCP 消 息 


n = dst->send(dst, b->pos, size); 


if (n == NGX_ERROR) { 
// 发 送 错 误 时 直接 结束 请 求 


ngx_mail proxy_close_ session(s); 
return; 





} 
if (n > 0) { 
// 更 新 消息 缓冲 区 


b->pos += n;// 如 果 缓 冲 区 中 的 消息 全 部 发 送 完 ， 则 清空 缓冲 区 以 复 用 


if (b->pos == b->last) { 
b->pos = b->start; 
b->last = b->start; 


} 
} 
// 为 下 面 读 取 


TCP 消 息 做 准备 ， 先 计算 接收 缓冲 区 上 的 空闲 空间 大 小 


size = b->end - b->last,; 
// 检查 空闲 缓冲 区 大 小 是 否 大 于 


@， 以 及 源 连 接 上 当前 是 否 可 读 


if (Size && src->read->ready) { 
c->l0g->action = recv_action,; 
// 调用 


recv 方 法 由 
Src 源 连接 上 接收 


TCP 消 息 


n = Src->recv(Src，b->]last，Size)， 
// 如 果 没有 读 取 到 内 容 ， 或 者 对 方 主动 关闭 了 


TCP 连 接 ， 则 跳出 循环 


if (n == NGX_AGAIN || n == 0) { 
break; 
} 


if (n > 0) { 
// 如 果 读 取 到 了 消息 ， 则 应 试图 在 本 次 


ngx_mail_proxy_handler 方 法 的 执行 中 将 它 立 即 发 送出 去 








4 
do_write = 1; 
// 更 新 消息 缓冲 区 
b->last += Nn; 
// 重新 执行 循环 ， 检 查 是 否 可 以 立即 转发 出 去 
continue 
if (n == NGX_ERROR) { 
src->read->eof = 1; 
} 
} 
break; 
} 
c->l0g->action = "proxying"; 
// 如 果 上 、 下 游 间 的 连接 中 断 ， 则 结束 透 传 流程 
if ((s->connection->read->eof && s->buffer->pos == s->buffer->last) || (s->prox) 
{ 
action = C->1og->action; 
c->l0g->action = NULL; 
c->l0g->action = action; 
ngx_mail_proxy_close_session(s); 
return; 
} 
// 下 面 将 会 把 


Nginx 与 上 、 下 游 


TCP 连 接 上 的 





/ 写 事 件 再 次 添加 到 


epoll 中 监控 





If (ngx_handle write event(dst->write, 0) != NGX_ OK) { 
ngx_mail_proxy_close_session(s); 
return; 





If (ngx_handle read event(dst->read, 0) != NGX _ OK) { 
ngx_mail_proxy_close_session(s); 
return; 





If (ngx_handle write event(src->write, 0) != NGX_ OK) { 
ngx_mail_proxy_close_session(s); 
return; 








If (ngx_handle_ read event(src->read, 0) != NGX _ OK) { 
ngx_mail_proxy_close_session(s); 
return; 





} 
/* 接 收 下 游客 户 端的 消息 时 还 是 需要 检查 超时 的 ， 防 止 “ 僵 死 ” 的 客户 端 占用 
Nginx 服 务 器 资源 


4 
if (c == s->connection) { 
pcf = ngx_mail get module srv_conf(s, ngx_mail proxy_module); 
ngx_add timer(c->read, pcf->timeout); 








可 以 看 到 ，ngx_mail_proxy_handler 方 法 很 简单 ， 不 过 百 行 代码 就 完成 了 透 传 功能 。 至 于 


138 小 续 


本 章 介 绍 了 Nginx 是 如 何 设 计 并 实现 官方 提供 的 邮件 代理 服务 如 
的 ， 当 需要 支持 新 的 邮件 协议 时 ， 类 似 于 HTTP 框 架 的 邮件 框架 可 以 较 
容易 地 集成 新 的 邮件 模块 。 邮 件 框架 和 HTTP 框 以 都 是 应 用 事件 框架 很 
好 的 例子 。 如 果 用 户 更 希望 Nginx 作 为 基于 TCP 的 其 他 应 用 层 协 议 服务 
器 ， 而 不 是 局 限于 Web 服 务 器 ， 那 么 可 以 对 比 和 参考 这 两 个 框 染 ， 编 写 
一 种 新 的 Nginx 模 块 ， 从 而 充分 利用 Nginx 压 层 的 强大 设计 功能 。 








第 14 章 ”进程 间 的 通信 机 制 


本 章 并 不 是 说 明 Linux 下 有 哪些 进程 通信 方式 ， 而 是 为 了 说 明 Nginx 
选择 了 哪些 方式 来 同步 master 进 程 和 多 个 worker 进 程 间 的 数据 ，Nginx 框 
架 是 怎样 重新 封装 了 这 些 进 程 间 通 信 方 式 的 ， 以 及 在 开发 Nginx 模 块 时 
该 怎样 使 用 这 些 封装 过 的 方法 。 


如 


Nginx 由 一 个 master 进 程 和 多 个 worker 进 程 组 成 ， 但 master 进 程 或 者 
worker 进 程 中 并 不 会 再 创建 线程 (Nginx 的 多 线程 机 制 一 直 停 留 在 测试 
状态 ， 虽 然 不 排除 未 来 Nginx 可 能 发 布 支 持 多 线程 版 本 的 可 能 性 ， 但 直 
到 目前 最 新 的 1.2.x 版 本 仍然 未 支持 多 线程 ) ， 因 此 ， 本 章 的 内 容 不 会 涉 
及 线程 间 的 通信 。 





14.1 概述 


Linux 提 供 了 多 种 进程 间 传 递 消 息 的 方式 ， 如 共 胖 内 存 、 套 接 字 、 
管道 、 消 奶 队列、 信号 等 ， 每 种 方式 都 有 其 优 缺 点 ， 而 Nginx 框 架 使 用 
了 3 种 传递 消息 传递 方式 : 共享 内 存 、 僚 接 字 、 信 号 。 在 14.2 节 将 会 介 
绍 Nginx 是 怎样 使 用 、 封 闭 共 译 内 存 的 ; 在 14.4 节 会 介绍 进程 间 怎 样 使 
用 套 接 字 通 信 ， 以 及 如 何 使 用 基于 套 接 字 封 逆 的 Nginx 频 道 ， 在 14.5 市 
中 将 会 介绍 进程 间 怎 样 通过 发 送 、 接 收 信号 来 传递 消 乱 。 








在 多 个 进程 访问 共享 资源 时 ， 还 需要 提供 一 种 机 制 使 各 个 进程 有 
序 、 安 全 地 访问 资源 ， 避 免 并 发 访问 带 来 的 未 知 结果 。Nginx 主 要 使 用 
了 3 种 同步 方式 : 原子 操作 、 信 号 量 、 文 件 锁 。 在 14.3 节 将 会 介绍 在 
Nginx 中 原子 操作 是 怎样 实现 的 ， 同 时 还 会 介绍 基于 原子 变量 实现 的 自 
旋 锁 ;， 在 14.6 市 将 会 介绍 信号 量 ， 与 “信号 ”不 同 的 是 ， 中 文 译 名 仪 有 一 
字 之 差 的 “信号 量 ”" 其 实 是 用 于 同步 代码 段 的 执行 的 ， 在 14.7 市 将 会 介绍 
文件 锁 。 


























由 于 Nginx 的 每 个 worker 进 程 都 会 同时 处 理 干 万 个 请 求 ， 所 以 处 理 
任何 一 个 请 求 时 都 不 应 该 阻塞 当前 进程 处 理 后 续 的 其 他 请 求 。 例 如 ， 不 
要 随意 地 使 用 信号 量 互 太 锁 ， 这 会 使 得 worker 进 程 在 得 不 到 锁 时 进入 睡 
眠 状态 ， 从 而 导致 这 个 worker 进 程 上 的 其 他 请 求 被 <“ 饿 死 ”。 鉴 于 此 ， 


Nginx 使 用 原子 操作 、 信 号 量 和 文件 锁 实 现 了 一 套 ngx_shmtx_t 互 斥 锁 ， 
当 操 作 系 统 支持 原子 操作 时 ngx_shmtx_t 就 由 原子 变量 实现 ， 和 否则 将 由 





文件 锁 来 实现 。 顾 名 思 义 ，ngx_shmtx_t 锁 是 可 以 在 共享 内 存 上 使 用 


的 ， 它 是 Nginx 中 最 常见 的 锁 。 


14.2 ”共享 内 存 


共享 内 存 是 Linux 下 提供 的 最 基本 的 进程 间 通 信 方 法 ， 它 通过 mmap 
或 者 shmget 系 统 调用 在 内 存 中 创建 了 一 块 连续 的 线性 地 址 空间 ， 而 通过 
munmap 或 者 shmdt 系 统 调 用 可 以 释放 这 块 内 存 。 使 用 共享 内 存 的 好 处 是 
当 多 个 进程 使 用 同一 块 共享 内 存 时 ， 在 任何 一 个 进程 修改 了 共享 内 存 中 
的 内 容 后 ， 其 他 进程 通过 访问 这 段 共享 内 存 都 能 够 得 到 修改 后 的 内 容 。 








人 @@ 注 总。 吉 然 mmap 可 以 以 磋 盘 文件 的 方式 映射 共享 内 存 ， 但 在 
Nginx 封 装 的 共享 内 存 操作 方法 中 是 没有 使 用 到 映射 文件 功能 的 。 


Nginx 定 义 了 ngx_shm t 结 构 体 ， 用 于 摘 述 一 块 共享 内 存 ， 代 码 如 下 
所 示 。 





typedef struct { 
// 指向 共享 内 存 的 起 始 地 址 


u_char *addr; 
// 共享 内 存 的 长 度 


size_t size 
// 和 


ngx_str_t name; 
// 记录 日 志 的 


ngx_1og 七 对 象 


ngx_log_t *1og 
// 表示 共享 内 存 是 否 已 经 分 配 过 的 标志 位 ， 为 


1 时 表示 已 经 存在 


ngx_uint_t exists; 
} ngx_shm_t; 





操作 ngx_shm _t 结 构 体 的 方法 有 以 下 两 个 : ngx_shm_alloc 用 于 分 配 
新 的 共享 内 存 ， 而 ngx_shm _free 用 于 释放 已 经 存在 的 共享 内 存 。 在 描述 
这 两 个 方法 前 ， 先 以 mmap 为 例 说 明 Linux 是 怎样 向 应 用 程序 提供 共享 内 
存 的 ， 如 下 所 示 。 








void *mmap(void *start, size t length, int prot, int flags, 
int fd, off_t offset); 





mmap 可 以 将 磁盘 文件 映射 到 内 存 中 ， 直 接 操作 内 存 时 Linux 内 核 将 
负责 同步 内 存 和 磁盘 文件 中 的 数据 ，f 参 数 就 指向 需要 同步 的 磁盘 文 
件 ， 而 offset 则 代表 从 文件 的 这 个 偏 移 量 处 开始 共享 ， 当 然 Nginx 没 有 使 
用 这 一 特性 。 当 flags 参 数 中 加 入 MAP_ANON 或 者 MAP_ANONYMOUS 
参数 时 表示 不 使 用 文件 映射 方式 ， 这 时 fd 和 offset 参 数 就 没有 意义 ， 也 不 
需要 传递 了 ， 此 时 的 mmap 方 法 和 ngx_shm_alloc 的 功能 几乎 完全 相同 。 
length 参 数 就 是 将 要 在 内 存 中 开辟 的 线性 地 址 空间 大 小 ， 而 prot 参 数 则 是 
操作 这 段 共享 内 存 的 方式 《如 只 读 或 者 可 读 可 写 ) ，start 参 数 说 明和 希望 
的 共享 内 存 起 始 映射 地 址 ， 当 然 ， 通 常 都 会 把 start 设 为 NULL 空 指针 。 








先 来 看 看 如 何 使 用 mmap 实 现 ngx_shm_alloc 方 法 ， 代 码 如 下 。 





ngx_int_t ngx_shm_alloc(ngx_shm_t *shm) 





// 开辟 一 块 
Shm->size 大 小 且 可 以 读 
/ 写 的 共享 内 存 ， 内 存 首 地 址 存放 在 


addr 中 


shm->addr = (u_char *) mmap(NULL, shm->size, 
PROT_READ | PROT_WRITE, 
MAP_ANON | MAP_SHARED, -1, 0); 
if (shm->addr == MAP_FAILED) { 
return NGX_ERROR,; 


} 
return NGX_OK; 





这 里 不 再 介绍 shmget 方 法 申请 共享 内 存 的 方式 ， 它 与 上 述 代 码 相 
| 以。 


当 不 再 使 用 共享 内 存 时 ， 需 要 调用 munmap 或 者 shmdt 来 释放 共享 内 
存 ， 这 里 还 是 以 与 nmap 配 对 的 munmap 为 例 来 说 明 。 





int munmap(void *start，Size _t length); 





其 中 ，start 参 数 指 癌 共享 内 存 的 首 地 址 ， 而 length 参 数 表示 这 上 段 共 
享 内 存 的 长 度 。 下 面 看 看 ngx_shm_free 方 法 是 怎样 通过 munmap 来 释放 
共享 内 存 的 。 





void ngx_shm_free(ngx_shm_t *shm) 


// 使 用 
ngx_shm_t 中 的 
addr 和 
Sjize 参 数 调 用 


munmap 释 放 共 享 内 存 即 可 


if (munmap((void *) shm->addr, shm->size) == -1) { 
ngx_log_error(NGX_ LOG ALERT, shm->log, ngx_errno, "munmap(%p, %uz) failed", 
} 


} 











Nginx 各 进程 间 共 享 数据 的 主要 方式 就 是 使 用 共享 内 存 〈 在 使 用 共 

享 内 存 时 ，Nginx 一 般 是 由 master 进 程 创建 ， 在 master 进 程 fork 出 worker 

子 进程 后 ， 所 有 的 进程 开始 使 用 这 块 内 存 中 的 数据 ，。 在 开发 Nginx 模 

块 时 如 果 需 要 使 用 它 ， 不 妨 用 Nginx 已 经 封装 好 的 ngx_shm_alloc 方 法 和 

ngx_shm_free 方 法 ， 它 们 有 3 种 实现 (不 映射 文件 使 用 mmap 分 配 共享 内 
存 、 以 /dev/zero 文 件 使 用 mmap 映 射 共 享 内 存 、 用 shmget 调 用 来 分 配 共享 
内 存 ) ， 对 于 Nginx 的 跨 平 台 特 性 考虑 得 很 周到 。 下 面 以 一 个 统计 HTTP 
框架 连接 状况 的 例子 来 说 明 共 享 内 存 的 用 法 。 





作为 Web 服 务 咒 ，Nginx 具 有 统计 整个 服务 器 中 HTTP 连接 状况 的 功 
能 (不 是 某 一 个 Nginx worker 进 程 的 状况 ， 而 是 所 有 worker 进 程 连 接 状 
况 的 总 和 ) 。 例 如 ， 可 以 用 于 统计 茶 一 时 刻下 Nginx 已 经 处 理 过 的 连接 
状况 。 下 面 定义 的 6 个 原子 变量 融 是 用 于 统计 





ngx_http_stub_status_module 模 块 连接 状况 的 ， 如 下 所 示 。 





// 已 经 建立 成 功 过 的 


TCP 连 接 数 


ngx_atomic_t ngx_stat_acceptedo0; 
ngx_atomic t *ngx_stat accepted = &ngx_stat_accepted0 
/* 已 经 从 


ngx_cycle_ tt 核心 结构 体 的 


free_connections 连 接 池 中 获取 到 


ngx_connection tt 对 象 的 活路 连接 数 


*/ 

ngx_atomic_t ngx_stat_active0 ; 

ngx_atomic t *ngx_stat active = &ngx_stat_activeg0 
/* 连 接 建 立成 功 且 获取 到 


ngx_connection_t 结 构 体 后 ， 已 经 分 配 过 内 存 池 ， 并 且 在 表示 初始 化 了 读 


/ 写 事件 后 的 连接 数 


* 

ngx_atomic_t ngx_stat_handledo,; 

ngx_atomic t *ngx_stat_handled = &ngx_stat_handledo0 
// 已 经 由 


HTTP 模 块 处 理 过 的 连接 数 


ngx_atomic t ngx_stat_requests0; 
ngx_atomic t *ngx_stat_requests = &ngx_stat_requestso0; 
// 正在 接收 


TCP 流 的 连接 数 


ngx_atomic_t ngx_stat_readingo0; 
ngx_atomic t *ngx_stat_reading = &ngx_stat_readingo0; 
// 正在 发 送 


TCP 流 的 连接 数 


ngx_atomic_t ngx_stat_writingo 
ngx_atomic t *ngx_stat writing = &ngx_stat_writingo， 





ngx_atomic t 原 子 变 量 将 会 在 14.3 贡 详细 介绍 ， 本 节 仅 关注 这 6 个 原 
子 变量 是 如 何 使 用 共享 内 存在 多 个 worker 进 程 中 使 用 这 些 统计 变量 的 。 





size _t size, cl; 
ngx_shm_t shm; 
/* 计 算出 需要 使 用 的 共享 内 存 的 大 小 。 为 什么 每 个 统计 成 员 需 要 使 用 


128 字 节 呢 ?这 似乎 太 大 了 ， 看 上 去 ， 每 个 


ngx_atomic_t 原 子 交 量 最 多 需要 


8 字 节 而 已 。 其 实 是 因为 





Nginx 充 分 考虑 了 


CPU 的 二 级 缓存 。 在 目前 许多 


CPU 架构 下 缓存 行 的 大 小 都 是 


128 字 节 ， 而 下 面 需要 统计 的 变量 都 是 访问 非常 频繁 的 成 员 ， 同 时 它们 占用 的 内 存 又 非常 少 ， 所 以 乳 用 了 每 个 成 员 : 


128 字 节 存 放 的 形式 ， 这 样 速 度 更 快 


*/ 
cl 128 
size = cl /* ngx_accept mutex */ 
硅 -G1 /* ngx_connection counter */ 
cl /* ngx_temp_number */ 
LX. 演 光 本 


NGX_STAT_STUB 宏 后 才 会 统计 上 述 


6 个 原子 变量 


#1if 


(NGX_STAT_STUB) 


size += cl /* ngx_stat accepted */ 
+ Cl /* ngx_stat_handled */ 
+ C1 /* ngx_stat_requests */ 
+ cl /* ngx_stat_active */ 
C1 /* ngx_stat_reading */ 
+ cl; /* ngx_stat writing */ 
#endif 


ngx_ 


shm. 


shm. 


// 初始 化 描述 共享 内 存 的 


shm_t 结 构 体 


shm.size = size,; 

shm.name.len = sizeof("nginx_shared_ zone"); 
shm.name.data = (u_char *) "nginx_shared_ zone",; 
shm.1log = Cycle->1og ' 

// 开辟 一 块 共享 内 存 ， 共 享 内 存 的 大 小 为 


size 
if (ngx_shm alloc(&shm) != NGX_OK) { 
return NGX_ERROR,; 


} 
// 共享 内 存 的 首 地 址 就 在 


addr 成 员 中 


shared = shm.addr; 
// 原子 变量 类 型 的 


accept 锁 使 用 了 


128 字 节 的 共享 内 存 


ngx_accept_mutex_ptr = (ngx_atomic t *) shared,; 
// ngx_accept_mutex 就 是 负载 均衡 锁 ， 





Spin 值 为 


-1 则 是 告诉 


Nginx 这 把 锁 不 可 以 使 进程 进入 睡眠 状态 ， 详 见 





14.8 节 


*/ 
ngx_accept_mutex.spin = (ngx_uint_t) -1; 
/* 原 子 变量 类 型 的 


ngx_connection_counter 将 统计 所 有 建立 过 的 连接 数 (包括 主 动 发 起 的 连接 ) 


A 

ngx_connection counter = (ngx_atomic t *) (Shared + 1 * cl); 
#if (NGX_STAT_STUB) 

// 依次 初始 化 需要 统计 的 


6 个 原子 变量 ， 也 就 是 使 用 共享 内 存 作为 原子 变量 


ngx_stat_accepted = (ngx_atomic t *) (Shared + 3 * cl); 

ngx_stat_handled = (ngx_atomic t *) (shared + 4 * cl); 

ngx_stat_requests = (ngx atomic t *) (shared + 5 * cl]); 

ngx_stat_active = (ngx_atomic t *) (shared + 6 * cl); 

ngx_stat_reading = (ngx_atomic t *) (Shared + 7 * cl); 

ngx_stat writing = (ngx_atomic t *) (shared + 8 * cl); 
#endif 





这 6 个 统计 变量 在 初始 化 后 ， 在 处 理 请 求 的 流程 中 由 于 其 意义 不 
同 ， 所 以 其 值 会 有 所 变化 。 例 如 ， 在 HITP 框 架 中 ， 刚 开始 接收 客户 端 
的 HTTP 请 求 时 使 用 的 是 ngx_http_init_request 方 法 ， 在 这 个 方法 中 就 会 
将 ngx_stat_reading 统 计 变量 加 1， 表 示 正 处 于 接收 用 户 请 求 的 连接 数 加 
1， 如 下 所 示 。 











(void) ngx_atomic _ fetch add(ngx_stat_reading, 1); 








而 当 读 取 完 请 求 时 ， 如 在 ngx_http_process_request 方 法 中 ， 开 始 处 
理 用 户 请 求 〈 不 再 接收 TCP 消 息 ) ， 这 时 会 把 ngx_stat_reading 统 计 变 量 
减 1， 如 下 所 示 。 





(void) ngx_atomic _ fetch add(ngx_stat_reading, -1); 











这 6 个 统计 变量 都 是 在 关键 的 流程 中 进行 维护 的 ， 每 个 worker 进 程 
修改 的 都 是 共享 内 存 中 的 统计 变量 ， 它 们 对 于 整个 Nginx 服 务 来 说 是 全 
局 有 效 的 。ngx_http_stub_status_module 模 块 将 负责 在 接收 到 相应 的 
HTTP 查 询 请 求 后 ， 把 这 些 统计 变量 以 HTTP 啊 应 的 方式 发 送 给 客户 端 。 
该 模块 也 可 以 作为 14.3 节 原子 变量 的 使 用 案例 。 














14.3 ”原子 操作 


能 够 执行 原子 操作 的 原子 变量 只 有 整 型 ， 包 括 无 符 写 整 型 
ngx_atomic_uint_t 和 有 符号 整 型 ngx_atomic_t， 这 两 种 类 型 都 使 用 了 
volatile 关 键 字 告诉 C 编 译 占 不 要 做 优化 。 





想 要 使 用 原子 操作 来 修改 、 获 取 整 型 变量 ， 目 然 不 能 使 用 加 减 号 ， 
而 要 使 用 Nginx 提 供 的 两 个 方法 : ngx_atomic_cmp_set 和 
ngx_atomic_fetch_add。 这 两 个 方法 都 可 以 用 来 修改 原子 变量 的 值 ， 而 
ngx_atomic_cmp_set 方 法 同时 还 可 以 比较 原子 变量 的 值 ， 下 面具 体 看 看 
这 两 个 方法 。 








static ngx_inline ngx_atomic_uint_t 
ngx_atomic_ cmp_set(ngx_atomic t *lock, ngx_atomic uint_t old, 
ngx_atomic_ uint_t set) 





ngx_atomic_cmp_set 方 法 会 将 old 参 数 与 原子 变量 lock 的 值 做 比较 ， 
如 果 它 们 相等 ， 则 把 lock 设 为 参数 set， 同 时 方法 返回 1;， 如 果 它 们 不 相 
等 ， 则 不 做 任何 修改 ， 返 回 0。 





static ngx_inline ngx_atomic_int_t 
ngx_atomic_ fetch_ add(ngx_atomic t *value, ngx_atomic_int_t add) 








ngx_atomic_fetch_add 方 法 会 把 原子 变量 value 的 值 加 上 参数 add， 同 


时 返回 之 前 value 的 值 。 





在 Nginx 各 种 锁 的 实现 中 ， 可 以 看 到 原子 变量 和 这 两 个 方法 的 多 种 
用 法 。 


即使 操作 系统 的 内 核 无 法 提供 原子 性 的 操作 ， 那 么 Nginx 也 会 对 上 
述 两 个 方法 提供 一 种 实现 ， 这 在 14.3.1 节 中 会 简单 说 明 ; 对 于 各 种 硬件 
体系 架构 ， 原 子 操作 的 实现 不 尽 相 同 ， 在 14.3.2 节 中 将 会 以 最 常见 的 
X86 架 构 为 例 ， 说 明 Nginx 是 怎样 实现 上 述 两 个 原子 操作 方法 的 。 在 
14.3.3 节 ， 介 绍 Nginx 封 装 的 ngx_spinlock 自 旋 锁 是 怎样 使 用 原子 变量 实 
现 的 。 








14.3.1 不 支持 原子 库 下 的 原子 操作 


当 无 法 实现 原子 操作 时 ， 就 只 能 用 volatile 关 键 字 在 C 语 言 级 别 上 模 
拟 原 子 操 作 了 。 事 实 上 ， 目 前 绝 大 多 数 体 系 架构 都 是 支持 原子 操作 的 ， 
给 出 这 一 节 内 容 更 多 的 是 方便 读者 理解 ngx_atomic_cmp_set 方 法 和 
ngx_atomic_fetch_add 方 法 的 意义 。 先 来 看 看 ngx_atomic_cmp_set 方 法 的 
实现 ， 如 下 所 示 。 








static ngx_inline ngx_atomic uint_t 
ngx_atomic_ cmp_set(ngx_atomic t *lock, ngx_atomic uint_t old, 
ngx_atomic_uint_t set) 


// 当 原 子 变 量 


lock 与 


01d 相 等 时 ， 才 能 把 


Set 设 置 到 


lock 中 并 返回 


If (*lock == old) { 
*lock = set,; 
return 1; 


} 
// 若 原 子 变 量 


lock 与 


01d 不 相等 ， 则 返回 


return 0; 





ngx_atomic_fetch_add 方 法 的 实现 也 很 简单 ， 如 下 所 示 。 





static ngx_inline ngx_atomic_ int_t 
ngx_atomic fetch add(ngx_atomic t *value, ngx_atomic_int_t add) 


{ 





ngx_atomic_int t old; 
// 将 原子 变量 


Value 加 上 


add 值 之 后 ， 再 返回 原先 


Value 的 值 


old = *Value 
*value += add; 
return old; 


14.3.2”X86 架 构 下 的 原子 操作 


Nginx 要 在 源 代码 中 实现 对 整 型 的 原子 操作 ， 目 然 必 须 通 过 内 联 汇 
编 语言 下 接 操作 硬件 才能 做 到 ， 本 节 以 基于 x86 的 SMP 多 核 架 构 为 例 来 
看 看 Nginx 是 如 何 实现 这 两 个 基本 的 原子 操作 的 《由 于 参考 着 x86 架 构 下 
的 实现 即 可 以 简单 地 推导 出 其 他 架构 下 的 实现 ， 故 其 他 架构 下 的 原子 操 
作 实 现 方法 不 再 一 一 说 明 ) 。 








使 用 GCC 编译 器 在 C 语 言 中 肉 入 汇编 语言 的 方式 是 使 用 _asm__ 关 
键 字 ， 如 下 所 示 。 


asm volatile ( 汇编 语句 部 分 


; 输出 部 分 


: 输入 部 分 





以 上 加 入 的 volatile 关 键 字 用 于 限制 GCC 编译 需 对 这 段 代 码 做 优化 。 





这 段 内 联 的 汇编 语言 包括 4 个 部 分 。 


(1) 汇编 语句 部 分 





引号 中 所 包含 的 汇编 语句 可 以 直接 用 占 位 符 % 来 引用 C 语 言 中 的 变 
量 (最 多 10 个 ，%0~%9) 。 





下 面 简单 介绍 一 下 随后 用 到 的 两 个 汇编 语句 ， 先 来 看 看 cmpxchglr， 
[m] 这 个 语句 ，Nginx 源 代码 中 对 这 一 汇编 语句 有 一 段 伪 代码 注释 ， 如 下 
所 示 。 





// 如 果 


eax 寄 存 器 中 的 值 等 于 


m 
if (eax == [m]) { 
// 将 


zf 标志 位 设 为 


m 值 设 为 


r 
[m] = r; 
// 如 果 


eax 寄 存 器 中 的 值 不 等 于 


m 
} else { 
// zf 标志 位 设 为 


0 
zf = 0; 
// 将 


eax 寄 存 器 中 的 值 设 为 


eax = [m]; 





从 上 面 这 段 伪 代 人 码 可 以 看 出 ，cmpxchgl zr,[m] 语 句 首 先 会 用 m 比 较 
eax 寄 存 器 中 的 值 ， 如 果 相 等 ， 则 把 m 的 值 设 为 r， 同 时 将 zf 标志 位 设 为 
1; 否则 将 zf 标志 位 设 为 0。 





再 看 一 个 语句 seterm]， 它 正好 配合 着 上 面 的 cmpxchgl 语 句 使 用 ， 
里 不 妨 简单 地 认为 它 的 作用 就 是 将 zf 标志 位 中 的 0 或 者 1 设置 到 mm 中 。 





(2) 输出 部 分 

这 部 分 可 以 将 寄存 器 中 的 值 设 置 到 C 语 言 的 变量 中 。 
(3) 输入 部 分 

可 以 将 C 语 言 中 的 变量 设置 到 寄存 器 中 。 

(4) 破坏 描述 部 分 


通知 编译 器 使 用 了 哪些 寄存 器 、 内 存 。 





简单 了 解 了 GCC 如 何 内 联 汇编 语言 后 ， 下 面 来 看 看 


ngx_atomic_cmp_set 方 法 的 实现 ， 如 下 所 示 。 





static ngx_inline ngx_atomic uint_t 

ngx_atomic_ cmp_set(ngx_atomic t *lock, ngx_atomic uint_t old, 
ngx_atomic_uint_t set) 

{ 


u_char res; 


// 在 


C0 语言 中 溢 入 汇编 语言 


_asm _ volatile (人 
// 多 核 架构 下 首先 锁 住 总 线 


相 lock; . 
// 将 


*1lock 的 值 与 
eaX 寄 存 器 中 的 

01d 相 比较 ， 如 果 相等 ， 则 置 
*]ock 的 值 为 


set 
"cmpxchgl %3, %1;" 
// cmpxchgl1 的 比较 若是 相等 ， 则 把 


zf 标志 位 
1 写 入 
res 变 量 ， 否 则 


res 为 


"Sete %0O;" 
: "=a" (res) : "m" (*]lock)，"a"” (ol1d), "r" (set) : "cc", "memory"); 
return res,; 


现在 简单 地 说 明 一 下 上 述 代 码 ， 在 嵌入 汇编 语言 的 输入 部 分 ，"m" 
(*lock) 表 示 *lock 变 量 是 在 内 存 中 ， 操 作 *lock 时 直接 通过 内 存 〔 不 使 用 
寄存 器 ) 处理 ， 而 "a"(old) 表 示 把 old 变 量 写 入 eax 寄 存 器 中 ，"r"(set) 表 示 
把 set 变 量 写 入 通用 寄存 器 中 ， 这 些 都 是 在 为 cmpxchgl 语 句 做 准 
备 。“cmpxchgl%3,%1” 相 当 于 “cmpxchglset*lock”( 含 义 参照 上 面 介绍 过 
的 伪 代 码 ) 。 这 3 行 汇编 语句 的 意思 如 下 : 首先 锁 住 总 线 防 止 多核 的 并 
发 执行 ， 接 着 判断 原子 变量 *lock 与 old 值 是 否 相 等 ， 若 相等 ， 则 把 *lock 
值 设 为 set， 同 时 设 res 为 1， 方 法 返回 ; 若 不 相等 ， 则 设 res 为 0， 方 法 返 
回 。 











在 了 解 ngx_atomic_fetch_add 方 法 前 ， 再 介绍 一 个 汇编 语句 xaddl。 
下 面 先 来 看 看 Nginx 对 “xaddlr[m]” 语 名 做 的 伪 码 注释 ， 如 下 所 示 。 





temp = [m]; 
[m] += r; 
r = temp; 





可 以 看 到 ，xaddl 执 行 后 [m] 值 将 为 r 和 [m] 之 和 ， 而 r 中 的 值 为 原 [m] 
值 。 现 在 看 看 ngx_atomic_fetch_add 方 法 是 如 何 实现 的 ， 如 下 所 示 。 





static ngx_inline ngx_atomic_ int_t 
ngx_atomic_ fetch_ add(ngx_atomic t *value, ngx_atomic_int_t add) 


{ 





_asm _ volatile (人 
// 首先 锁 住 总 线 


"lock;" 
// *value 的 值 将 会 等 于 原先 


*xValue 值 与 


add 值 之 和 ， 而 


add 为 原 


*xValue 值 


"Xadd1 %0, %1;" 
:"+r" (add) : "m" (*value) : "cc", "memory"); 
return add; 


} 





可 见 ，ngx_atomic fetch_add 将 使 得 *value 原 子 变 量 的 值 加 上 add， 
同时 返回 原先 *value 的 值 。 


14.3.3” 自 旋 锁 


基于 原子 操作 ，Nginx 实 现 了 一 个 自 旋 锁 。 目 旋 锁 是 一 种 非 睡 虐 
锁 ， 也 就 是 说 ， 茶 进程 如 果 试 图 获得 目 旋 锁 ， 当 发 现 锁 已 经 个 其 他 进程 
获得 时 ， 那 么 不 会 使 得 当前 进程 进入 睡 虐 状 态 ， 而 是 始终 保持 进程 在 可 
执行 状态 ， 每 当 内 核 调 度 到 这 个 进程 执行 时 就 持续 检查 是 否 可 以 获取 到 
锁 。 在 拿 不 到 锁 时 ， 这 个 进程 的 代码 将 会 一 直 在 自 旋 锁 代 码 处 执行 ， 直 
到 其 他 进程 释放 了 锁 且 当前 进程 获取 到 了 锁 后 ， 代 码 才 会 继续 癌 下 执 


/一 


介 。 











可 见 ， 目 旋 锁 主要 是 为 多 处 理 器 操作 系统 而 设置 的 ， 它 要 解决 的 共 
享 资 源 保护 场景 就 是 进程 使 用 锁 的 时 间 非 常 短 《〈《 如 采 锁 的 使 用 时 间 很 














和 久 ， 自 旋 锁 会 不 太 合适 ， 那 么 它 会 占用 大 量 的 CPU 资源 ) 。 在 14.6 节 和 
14.7 节 介绍 的 两 种 睡眠 锁 会 导致 进程 进入 睡眠 状态 。 睡 眠 锁 与 非 睡 眠 锁 
应 用 的 场景 不 同 ， 如 果 使 用 锁 的 进程 不 太 希 望 自己 进入 睡眠 状态 ， 特 别 
它 处 理 的 是 非常 核心 的 事件 时 ， 这 时 就 应 该 使 用 自 旋 锁 ， 其 实 大 部 分 情 
况 下 Nginx 的 worker 进 程 最 好 都 不 要 进入 睡眠 状态 ， 因 为 它 非常 繁忙 ， 
在 这 个 进程 的 epoll 上 可 能 会 有 十 万 甚至 百 万 的 TCP 连 接 等 竺 着 处 理 ， 进 
程 一 旦 睡眠 后 必须 等 待 其 他 事件 的 唤醒 ， 这 中 间 极 其 频繁 的 进程 间 切 换 
带 来 的 负载 消耗 可 能 无 法 让 用 户 接 受 。 


人 @@O 注意 自 放 锁 对 于 单 处 理 器 操作 系统 来 说 一 样 是 有 效 的 ， 不 进 
入 睡眠 状态 并 不 意味 着 其 他 可 执行 状态 的 进程 得 不 到 执行 。Linux 内 核 
中 对 于 每 个 处 理 器 都 有 一 个 运行 队列 ， 自 旋 锁 可 以 仅仅 调整 当前 进程 在 
运行 队列 中 的 顺序 ， 或 者 调整 进程 的 时 间 片 ， 这 都 会 为 当前 处 理 器 上 的 
其 他 进程 提供 被 调度 的 机 会 ， 以 使 得 锁 被 其 他 进程 释放 ，。 





用 户 可 以 从 锁 的 使 用 时 间 长 短 角度 来 选择 使 用 哪 一 种 锁 。 当 锁 的 使 
用 时 间 很 短 时 ， 使 用 自 旋 锁 非 常 合 适 ， 尤 其 是 对 于 现在 普 衣 存在 的 多 核 
处 理 占 来 说 ， 这 样 的 开销 最 小 。 而 如 末 锁 的 使 用 时 间 很 长 时 ， 那 么 一 旦 
进程 拿 不 到 锁 束 不 应 该 再 执行 任何 操作 了 ， 这 时 应 该 使 用 睡眠 锁 将 系统 
资源 释放 给 其 他 进程 使 用 。 男 外 ， 如 果 进 程 拿 不 到 锁 ， 可 能 只 会 导致 菜 
一 类 请 求 〈 不 是 进程 上 的 所 有 请 求 ) 不 能 继续 执行 ， 而 epoll 上 的 其 他 请 
求 还 是 可 以 执行 的 ， 这 时 应 该 选用 非 阻塞 的 互 斥 锁 ， 而 不 能 使 用 目 旋 





锁 。 


下 面 介 绍 基于 原子 操作 的 目 旋 锁 方 法 ngx_spinlock 是 如 何 实现 的 。 
它 有 3 个 参数 ， 其 中 ，lock 参 数 就 是 原子 变量 表达 的 锁 ， 当 lock 值 为 0 时 
表示 锁 是 被 释放 的 ， 而 lock 值 不 为 0 时 则 表示 锁 已 经 被 某 个 进程 持 有 
了 ; value 参 数 表示 和 希望 当 锁 没有 被 任何 进程 持 有 时 《也 就 是 lock 值 为 
0) ， 把 lock 值 设 为 value 表 示 当 前 进程 持 有 了 锁 ; 第 三 个 参数 spin 表 示 在 
多 处 理 器 系统 内 ， 当 ngx_spinlock 方 法 没有 拿 到 锁 时 ， 当 前 进程 在 内 核 
的 一 次 调度 中 ， 该 方法 等 待 其 他 处 理 器 释放 锁 的 时 间 。 下 面 来 看 一 下 它 
的 源 代码 。 

















void ngx_spinlock(ngx_atomic t *lock, ngx_atomic int_t value, ngx_uint_t spin) 


ngx_uint_t i, n,; 
// 无 法 获取 锁 时 进程 的 代码 将 一 直 在 这 个 循环 中 执行 


for (;; ) 
// lock 为 


9 时 表示 锁 是 没有 被 其 他 进程 持 有 的 ， 这 时 将 
loCk 值 设 为 


Value 参数 表示 当前 进程 持 有 了 锁 


if (*lock == 0 && ngx_atomic cmp_set(lock, 90, value)) { 
// 获取 到 锁 后 


ngx_spinlock 方 法 才 会 返回 


return; 


} 
// ngx_ncpu 是 处 理 器 的 个 数 ， 当 它 大 于 


工时 表示 处 于 多 处 理 器 系统 中 


if (ngx_ncpu > 1) { 
/* 在 多 处 理 器 下 ， 更 好 的 做 法 是 当前 进程 不 要 立刻 “让 出 ”正在 使 用 的 


CPU 处 理 器 ， 而 是 等 待 一 段 时 间 ， 看 看 其 他 处 理 器 上 的 进程 是 否 会 释放 锁 ， 这 会 减少 进程 间 切 换 的 次 数 


人 
for (n= 1; n < spin; n <<= 1) { 
/* 注 意 ， 随 着 等 待 的 次 数 越 来 越 多 ， 实 际 去 检查 


]OCKk 是 否 释 放 的 频繁 会 越 来 越 小 。 为 什么 会 这 样 呢 ?因为 检查 
0OCK 值 更 消耗 

CPU， 而 执行 

ngx_cpu_pause 对 于 

CPU 的 能 耗 来 说 是 很 省 电 的 


2 
for (i = 0; i < n; i++) { 
/*ngx_cpu_pause 是 在 许多 架构 体系 中 专门 为 了 自 旋 锁 而 提供 的 指令 ， 它 会 告诉 


CPU 现在 处 于 自 旋 锁 等 待 状态 ， 通 常 一 些 
CPU 会 将 自己 置 于 节能 状态 ， 降 低 功 耗 。 注 意 ， 在 执行 
ngx_cpu_pause 后 ， 当 前 进程 没有 “让 出 ” 正 使 用 的 处 理 器 
*/ 
ngx_cpu_pause( ); 

} 

/* 检 查 锁 是 否 被 释放 了 ， 如 果 
]ock 值 为 
0 且 释 放 了 和 锁 后 ， 就 把 它 的 值 设 为 


Value， 当 前 进程 持 有 锁 成 功 并 返回 


if (*lock == 0 && ngx_atomic cmp_set(lock, ©0, value)) { 
return; 


} 
} 


} 

/* 当 前 进程 仍然 处 于 可 执行 状态 ,但 暂时 “让 出 ”处 理 器 ， 使 得 处 理 器 优先 调度 其 他 可 执行 状态 的 进程 ， 
for 循 环 代码 中 可 以 期 望 其 他 进程 释放 锁 。 注 意 ， 不 同 的 内 核 版 本 对 于 
sched_yield 系 统 调用 的 实现 可 能 是 不 同 的 ， 但 它们 的 目的 都 是 暂时 “让 出 ”处 理 器 


*/ 
ngx_sched_yield(); 
}} 





释放 锁 时 需要 Nginx 模 块 通过 ngx_atomic_cmp_set 方 法 将 原子 变量 
lock 值 设 为 0。 





可 以 看 到 ，ngx_spinlock 方 法 是 非常 高 效 的 目 旋 锁 ， 它 充分 考虑 了 
单 处 理 器 和 多 处 理 器 的 系统 ， 对 于 持 有 锁 时 间 非 常 短 的 场景 很 有 效率 。 


14.4 Nginx 频 道 


ngx_channel_t 频 道 是 Nginx master 进 程 与 worker 进 程 之 间 通 信 的 常用 
工具 ， 它 是 使 用 本 机 套 接 字 实 现 的 。 下 面 先 来 看 看 socketpair 方 法 ， 它 用 
于 创建 父子 进程 间 使 用 的 套 接 字 。 


int socketpair(int d, int type, int protocol, int sv[2]); 


这 个 方法 可 以 创建 一 对 关联 的 套 接 字 sv[2]。 下 面 依次 介绍 它 的 4 个 
参数 : 参数 d 表 示 域 ， 在 Linux 下 通常 取 值 为 AF_UNIX; type 取 值 为 
SOCK_STREAM 或 者 SOCK_DGRAM， 它 表示 在 套 接 字 上 使 用 的 是 TCP 
还 是 UDP; protocol 必 须 传递 0，sv[2] 是 一 个 含有 两 个 元 素 的 整 型 数组 ， 
实际 上 就 是 两 个 套 接 字 。 当 socketpair 返 回 0 时 ，sv[2] 这 两 个 套 接 字 创建 
成 功 ， 和 否则 socketpair 返 回 -1 表 示 失 败 。 





当 socketpair 执 行 成 功 时 ，sv[2] 这 两 个 套 接 字 具 备 下 列 关 系 : 问 
sv[0] 套 接 字 写 入 数据 ， 将 可 以 从 sv[1] 套 接 字 中 读 取 到 刚 写 入 的 数据 ， 同 
样 ， 疝 sv[1] 套 接 字 写 入 数据 ， 也 可 以 从 sv[0] 中 读 取 到 写 入 的 数据 。 通 
常 ， 在 父 、 子 进程 通信 前 ， 会 先 调 用 socketpair 方 法 创建 这 样 一 组 套 接 
字 ， 在 调用 fork 方 法 创建 出 子 进程 后 ， 将 会 在 父 进程 中 关闭 sv[1] 套 接 
字 ， 仅 使 用 sv[0] 套 接 字 用 于 向 子 进程 友 送 数据 以 及 接收 子 进程 发 送 来 的 
数据 ; 而 在 子 进程 中 则 关闭 sv[0] 套 接 字 ， 仅 使 用 sv[H] 套 接 字 既 可 以 接收 





父 进程 发 来 的 数据 ， 也 可 以 同 父 进程 发 送 数据 。 


再 来 介绍 一 下 ngx_channel t 频 道 。ngx_channel_t 结 构 体 是 Nginx 定 
义 的 master 父 进程 与 worker 子 进程 间 的 消 恩 格式 ， 如 下 所 示 。 





typedef struct { 
// 传递 的 


TCP 消 息 中 的 命令 


ngx_uint_t command; 
// 进程 


ID， 一 般 是 发 送 命令 方 的 进程 


ID 
ngx_pid_t pid; 
// 表示 发 送 命 令 方 在 


ngx_processes 进 程 数 组 间 的 序号 


ngx_int_t Slot 
// 通信 的 套 接 字句 柄 


ngx_fd fd ， 
} ngx_channel_t; 





这 个 消息 的 格式 似乎 过 于 简单 了 ， 没 错 ， 因 为 Nginx 仅 用 这 个 频道 
同步 master 进 程 与 worker 进 程 间 的 状态 ， 这 点 从 针对 command 成 员 已 经 
定义 的 命令 束 可 以 看 出 来 ， 如 下 所 示 。 





// 打开 频道 ， 使 用 频道 这 种 方式 通信 前 必须 发 送 的 命令 


#define NGX_CMD_OPEN_CHANNEL 1 
// 关闭 已 经 打开 的 频道 ， 实 际 上 也 就 是 关闭 套 接 字 


#define NGX_CMD_CLOSE_ CHANNEL 2 
// 要 求 接收 方正 常 地 退出 进程 


#define NGX_CMD_QUIT 3 
// 要 求 接收 方 强制 地 结束 进程 


#define NGX_CMD_ TERMINATE 4 
// 要 求 接收 方 重新 打开 进程 已 经 打开 过 的 文件 





#define NGX_CMD _ REOPEN 5 





在 8.6 闻 我 们 介绍 过 master 进 程 是 如 何 监控 、 管 理 worker 子 进程 的 ， 
那 图 8-8 中 的 master 义 是 如 何 启 动 、 集 止 worker 子 进程 的 呢 ? 正 是 通过 
socketpair 产 生 的 套 接 字 发 送 命令 的 ， 即 每 次 要 派生 一 个 子 进 程 之 前 ， 都 
会 先 调用 socketpair 方 法 。 在 Nginx 派 生子 进程 的 ngx_spawn_process 方 法 
中 ， 会 首先 派生 基于 TCP 的 套 接 字 ， 如 下 所 示 。 








ngx_pid t ngx_spawn process(ngx_cycle t *cycle, ngx_spawn_proc_pt proc, void *data, 





// ngx_processes[s].channel 数 组 正 是 将 要 用 于 父 、 子 进程 间 通 信 的 套 接 字 对 


If (socketpair(AF_UNIX, SOCK_STREAM, 0, ngx_processes[s].channel) == -1) 
{ 
return NGX_INVALID_PID ， 


} 
// 接 下 来 会 把 


channe1 套 接 字 对 都 设置 为 非 阻塞 模式 





上 段 代 码 提 到 的 ngx_processes 数 组 定义 了 Nginx 服 务 中 所 有 的 进 
程 ， 包 括 master 进 程 和 worker 进 程 ， 如 下 所 示 。 








#define NGX_MAX_PROCESSES 1024 
// 虽然 定义 了 


NGX_MAX_PROCESSES 个 成 员 , 但 已 经 使 用 的 元 素 仅 与 启动 的 进程 个 数 有 关 


ngx_process_t ngx_processes[NGX MAX_PROCESSES]; 





它 的 类 型 是 ngx_process_t， 对 于 频道 来 说 ， 这 个 结构 体 只 关心 它 的 


channel 成 员 。 





typedef struct { 


// Socketpair 创 建 的 套 接 字 对 


ngx_socket_t channel[2]; 
} ngx_process _t; 





如 何 使 用 频道 发 送 ngx_channel t 消 息 呢 ? Nginx 封 装 了 4 个 方法 ， 首 
先 来 看 看 用 于 发 送 消息 的 ngx_write_channel 方 法 。 








ngx_int_t ngx_write channel(ngx_socket _t s, ngx_channel _t *ch，Size_t size, ngx_log. 








这 里 的 s 参 数 是 要 使 用 的 TCP 套 接 字 ，ch 参 数 是 ngx_channel _t 类 型 的 
消息 ，size 参 数 是 ngx_channel t 结 构 体 的 大 小 ，log 参 数 是 日 志 对 象 。 


再 来 看 看 读 取消 息 的 方法 ngx_read_channel。 





ngx_int_t ngx_read_channel(ngx_socket_t s, ngx_channel t *ch, size t size, ngx_ log_t 











这 里 的 参数 意义 与 ngx_write_channel 方 法 完全 相同 ， 只 是 要 注意 s 套 
接 字 ， 它 与 发 送 方 使 用 的 s 套 接 字 是 配对 的 。 例 如 ， 在 Nginx 中 ， 目 前 仅 
存在 master 进 程 同 worker 进 程 发 送 消 息 的 场景 ， 这 时 对 于 socketpair 方 法 
创建 的 channel[2] 套 接 字 对 来 说 ，master 进 程 会 使 用 channel[0] 和 套 接 字 来 
发 送 消 轧 ， 而 workerj 进 程 则 会 使 用 channel[1] 套 接 字 来 接收 消 妃 。 








worker 进 程 是 怎样 调度 ngx_read_channe] 方 法 接收 频道 消息 呢 ? 毕竟 
Nginx 是 单线 程 程序 ， 这 唯一 的 线程 还 在 同时 处 理 大 量 的 用 户 请 求 呢 ! 
这 时 就 需要 使 用 ngx_add_channel_event 方 法 把 接收 频道 消息 的 套 接 字 添 
加 到 epol 中 了 ， 当 接收 到 父 进程 消息 时 子 进程 会 通过 epoll 的 事件 回调 相 
应 的 handler 方 法 来 处 理 这 个 频道 消息 ， 如 下 所 示 。 








ngx_int_t ngx_add_channel event(ngx_cycle t *cycle，ngx_fd t fd, 
ngx_int_t event, ngx_event_handler_pt handler); 








cycle 参 数目 然 是 每 个 Nginx 进 程 必须 具备 的 ngx_cycle_t 核 心 结构 
体 ;，fd 参 数 就 是 上 面 说 过 的 需要 接收 消 明 的 套 接 字 ， 对 于 worker 子 进程 





来 说 ， 就 是 对 应 的 channel[1] 套 接 字 ; event 参 数 是 需要 检测 的 事件 类 
型 ， 在 上 述 场景 下 必然 是 EPOLLIN; handler 参 数 指向 的 方法 就 是 用 于 读 
取 频 道 消 息 的 方法 ，Nginx 定 义 了 一 个 ngx_channel_handler 方 法 用 于 处 理 


频道 消息 。 





当 进 程 希望 关闭 这 个 频道 通信 方式 时 ， 可 以 调用 ngx_close_channel 
方法 ， 它 会 关闭 这 对 套 接 字 ， 如 下 所 示 。 





void ngx_close channel(ngx_fd t *fd, ngx_log t *]1og) ， 





参数 fd 就 是 上 面 说 过 的 channel[2] 套 接 字数 组 。 


14.5 信号 


Linux 提 供 了 以 信号 传递 进程 间 消 息 的 机 制 ，Nginx 在 管理 master 进 
程 和 worker 进 程 时 大 量 使 用 了 信和 号。 什么 是 信号 ? 它 是 一 种 非 第 短 的 消 
恩 ， 短 到 只 有 一 个 数字 。 在 中 文 译名 中 ， 信 号 相 比 下 文 将 要 介绍 的 信号 
量 只 少 了 一 个 字 ， 但 它们 完全 是 两 个 概念 ， 信 和 号 量 仅 用 于 同步 代码 段 ， 
而 信号 则 用 于 传递 消 轧 。 一 个 进程 可 以 同 另 外 一 个 进程 或 者 另外 一 组 进 
程 发 送信 号 消 轧 ， 通 知 目标 进程 执行 特定 的 代码 。 




















Linux 定 义 的 前 31 个 信号 是 最 常用 的 ，Nginx 则 通过 重 定义 其 中 一 些 
童 号 的 处 理 方法 来 使 用 信和 号， 如 接收 到 SIGUSR1 信 号 就 意味 着 需要 重新 
打开 文件 。 使 用 信号 时 Nginx 定 义 了 一 个 ngx_signal_t 结 构 体 用 于 描述 接 
收 到 信号 时 的 行为 ， 如 下 所 示 。 




















typedef struct { 
// 需要 处 理 的 信号 


int signo,; 
// 信号 对 应 的 字符 串 名 称 


char *signame; 
// 这 个 信号 对 应 着 的 


Nginx 命 令 


char *name; 
// 收 到 


Signo 信 号 后 就 会 回调 


handler 方 法 


void (*handler)(int signo); 
} ngx_signal t; 





另外 ，Nginx 还 定义 了 一 个 数组 ， 用 来 定义 进程 将 会 处 理 的 所 有 信 
号 。 例 如 : 





#define NGX_RECONFIGURE_SIGNAL HUP 
ngx_signal t signals[] = { 

{ ngx_signal value(NGX_ RECONFIGURE_SIGNAL), 
"SIG" ngx_value(NGX_ RECONFIGURE_SIGNAL), 
"reload", 
ngx_signal_handler }, 








上 面 的 例子 意味 着 在 接收 到 SIGHUP 信 号 后 ， 将 调用 
ngx_signal_handler 方 法 进行 处 理 ， 以 便 重 新 读 取 配 置 文件 ， 或 者 说 ， 当 
收 到 用 户 发 来 的 如 下 命令 时 : 








./Nginx -s reload 





这 个 新 启动 的 Nginx 进 程 会 向 实际 运行 的 Nginx 服 务 进程 发 送 SIGHUP 信 
号 (执行 这 个 命令 后 拉 起 的 Nginx 进 程 并 不 会 重新 启动 服务 器 ， 而 是 仪 
用 于 发 送信 号 ， 在 ngx_get_options 方 法 中 会 重 置 ngx_signal 全 局 变量 ， 而 
main 方 法 中 检查 到 其 非 0 时 就 会 调用 ngx_signal_process 方 法 癌 正 在 运行 





的 Nginx 服 务 发 送信 号 ， 之 后 main 方 法 就 会 返回 ， 新 启动 的 Nginx 进 程 退 
出 ，， 这 样 运 行 中 的 服务 进程 也 会 调用 ngx_signal_handler 方 法 来 处 理 这 


在 定义 了 ngx_signal_t 类 型 的 signals 数 组 后 ，ngx_init_signals 方 法 会 
初始 化 所 有 的 信号 ， 如 下 所 示 。 








ngx_int_t ngx_init_signals(ngx_log _t *]1odg) 
‘ 


ngx_signal t *sig; 
// Linux 内 核 使 用 的 信号 


Struct sigaction sa; 
// 遍历 


Signals 数 组 ， 处 理 每 一 个 


ngx_signal 七 类 型 的 结构 体 


for (sig = signals; sig->signo != 0; sig++) { 
ngx_memzero(&sa, sizeof(struct sigaction)); 
// 设置 信号 的 处 理 方法 为 


handler 方 法 
sa.sa_handler = sig->handler; 
// 将 

Sa 中 的 位 全 部 置 为 


sigemptyset(&sa.sa mask); 
// 向 


Linux 注 册 信 号 的 回调 方法 


if (sigaction(sig->signo, &sa, NULL) == -1) { 
ngx_1log_error(NGX_LOG_EMERG, log, ngx_errno, 
"sigaction(%s) failed", sig->signame); 
return NGX_ERROR ， 


} 
return NGX_OK; 





这 样 进程 就 可 以 处 理 信 号 了 。 如 果 用 户 和 希望 Nginx 处 理 更 多 的 信 
号 ， 那 么 可 以 直接 同 signals 数 组 中 添加 新 的 ngx_signal { 成 员 。 


14.6 ”信号 量 





言 号 量 与 信号 不 同 ， 它 不 像 信号 那样 用 来 传递 消息 ， 而 是 用 来 保证 
两 个 或 多 个 代码 段 不 被 并 发 访问 ， 是 一 种 保证 共 至 资源 有 序 访问 的 工 
具 。 使 用 信号 量 作为 互 斥 锁 有 可 能 导致 进程 睡 虑 ， 因 此 ， 要 谨慎 使 用 ， 
特别 是 对 于 Nginx 这 种 每 一 个 进程 同时 处 理 着 数 以 万 计 请 求 的 服务 器 来 
说 ， 这 种 导致 睡眠 的 操作 将 有 可 能 造成 性 能 大 幅 降低 。 








信号 量 提 供 的 用 法 非常 多 ， 但 Nginx 仅 把 它 作 为 简单 的 互 斥 锁 来 使 
用 ， 下 面 只 会 介绍 这 种 用 法 。 定 义 一 个 sem_t 类 型 的 变量 后 ， 即 可 围绕 





int sem init(sem t *sem, int pshared, unsigned int value); 





其 中 ， 参 数 sem 即 为 我 们 定义 的 信号 量 ， 而 参数 pshared 将 指明 sem 
信号 量 是 用 于 进程 间 同 步 还 是 用 于 线程 间 同 步 ， 当 pshared 为 0 时 表示 线 
程 间 同 步 ， 而 pshared 为 1 时 表示 进程 间 同 步 。 由 于 Nginx 的 每 个 进程 都 是 
单线 程 的 ， 因 此 将 参数 pshared 设 为 1 即 可 。 参 数 value 表 示 信 号 量 sem 的 
初始 值 。 下 面 看 看 在 ngx_shmtx_create 方 法 中 是 如 何 初 始 化 信号 量 的 。 











ngx_int_t ngx_shmtx_create(ngx_shmtx_t *mtx, void *addr, u_char *name) 





#if (NGX_HAVE_POSIX_SEM) 
// 信号 量 


mtx->sem 初 始 化 为 


9， 用 于 进程 间 通 信 


if (sem init(&mtx->sem, 1, 0) == -1) { 
ngx_1log_error(NGX_LOG ALERT, ngx_cycle->log, ngx_errno, 
"sem_ init() failed"); 
} else { 
mtx->semaphore = 1; 


} 
#endif 

return NGX_OK， 
} 





ngx_shmtx_t 结 构 体 将 会 在 14.8 节 中 介绍 。 可 以 看 到 ， 在 定义 了 
NGX_HAVE_POSIX_SEM 宏 后 ， 将 开始 使 用 信号 量 。 另 外 ， 
sem_destroy 方 法 可 以 销毁 信号 量 。 例 如 ; 





void ngx_shmtx_destory(ngx_shmtx_t *mtx ) 


#if (NGX_HAVE_POSIX_SEM) 
if (mtx->semaphore) { 
if (sem destroy(&mtx->sem) == -1) { 
ngx_1log_error(NGX_LOG ALERT, ngx_cycle->log, ngx_errno, "sem destroy() 


} 
#endif 





信和 号 量 是 如 何 实现 互 斥 锁 功 能 的 呢 ? 例如 ， 最 初 的 信号 量 sem 值 为 
0， 调 用 sem_post 方 法 将 会 把 sem 值 加 1， 这 个 操作 不 会 有 任何 阻塞 ; 调 
用 sem_wait 方 法 将 会 把 信号 量 sem 的 值 减 1， 如 果 sem 值 已 经 小 于 或 等 于 0 
了 ， 则 阻塞 住 当前 进程 (进程 会 进入 睡眠 状态 ) ， 直 到 其 他 进程 将 信号 


量 sem 的 值 改变 为 正 数 后 ， 这 时 才能 继续 通过 将 sem 减 1 而 使 得 当前 进程 
继续 同 下 执行 。 因 此 ，sem_post 方 法 可 以 实现 解锁 的 功能 ， 而 sem_wait 
方法 可 以 实现 加 锁 的 功能 。 


例如 ，ngx_shmtx_lock 方 法 在 加 锁 时 ， 有 可 能 到 使 用 sem_wait 的 分 
支 去 试图 获得 锁 ， 如 下 所 示 。 





void ngx_shmtx_lock(ngx_shmtx_t *mtx) 


// 如 果 没 有 拿 到 锁 ， 这 时 


NginxX 进 程 将 会 睡眠 ， 直 到 其 他 进程 释放 了 锁 


while (sem wait(&mtx->sem) == -1) { 





ngx_shmtx_lock 方 法 会 在 14.8 节 详细 说 明 。ngx_shmtx_unlock 方 法 在 
释放 锁 时 也 会 用 到 sem_post 方 法 ， 如 下 所 示 。 





void ngx_shmtx_unlock(ngx_shmtx_t *mtx) 


// 释放 信号 量 锁 时 是 不 会 使 进程 睡眠 的 


if (sem post(&mtx->sem) == -1) { 
ngx_log_error(NGX_LOG ALERT, ngx_cycle->log, ngx_errno, 


"Sem_post() failed while wake shmtx"); 








在 14.8 节 中 我 们 将 会 讨论 Nginx 有 是 如 何 让 原子 变量 和 信和 号 量 合作 以 
实现 局 效 互 斥 锁 的 。 


14.7 “文件 锁 


Linux 内 核 提 供 了 基于 文件 的 互 斤 锁 ， 而 Nginx 框 架 封 逆 了 3 个 方 
法 ， 提 供给 Nginx 模 块 使 用 文件 互 斥 锁 来 保护 共 孚 数据 。 下 面 首 先 介绍 
一 下 这 种 基于 文件 的 互 斥 锁 是 如 何 使 用 的 ， 其 实 很 简单 ， 通 过 fcnt 方 法 
就 可 以 实现 。 





int fcntl(int fd, int cmd, struct flock *]ock) ， 


这 个 方法 接收 3 个 参数 ， 其 中 参数 fd 是 打开 的 文件 句柄 ， 参 数 cmd 表 
示 执 行 的 锁 操 作 ， 参 数 lock 描 述 了 这 个 锁 的 信息 。 下 面 依次 说 明 这 3 个 


参数 。 


参数 fd 必须 是 已 经 成 功 打 开 的 文件 句柄 。 实 际 上 ，nginx.conf 文 件 中 
的 lock_file 配 置 项 指定 的 文件 路 符 ， 就 是 用 于 文件 互 斥 锁 的 ， 这 个 文件 
被 打开 后 得 到 的 句柄 ， 将 会 作为 fa 参数 传递 给 fcnt 方 法 ， 提 供 一 种 锁 机 
制 |。 


这 里 的 cmd 参 数 在 Nginx 中 只 会 有 两 个 值 : F_SETLK 和 
F_SETLKW， 它 们 都 表示 试图 获得 互 斥 锁 ， 但 使 用 F_SETLK 时 如 果 互 
斥 锁 已 经 被 其 他 进程 占用 ，fcnt 方 法 不 会 等 待 其 他 进程 释放 锁 且 自己 拿 
到 锁 后 才 返 回 ， 而 是 立即 返回 获取 互 斥 锁 失 败 ; 使 用 F_SETLKW 时 则 不 


同 ， 锁 被 占用 后 fcnt 方 法 会 一 直 等 待 ， 在 其 他 进程 没有 释放 锁 时 ， 当 前 
进程 就 会 阻 奢 在 fcntl 方 法 中 ， 这 种 阻 豆 会 导致 当前 进程 由 可 执行 状态 转 
为 睡眠 状态 。 





参数 lock 的 类 型 是 flock 结 构 体 ， 它 有 5 个 成 员 是 需要 用 户 关心 的 ， 
如 下 所 示 。 





struct flock 


// 锁 类 型 ， 取 值 为 


F_RDLCK、 


F_WRLCK 或 


F_UNLCK 
Short 1_type; 
// 锁 区 域 起 始 地 址 的 相对 位 置 


Short 1 whence; 
// 锁 区 域 起 始 地 址 偏 移 量 ， 同 


1_whence 共 同 确 定 锁 区 域 


Jong 1_ start,; 
// 锁 的 长 度 ， 


9 表示 锁 至 文件 末 


long 1_len; 
// 拥有 锁 的 进程 


ID 
long 1 pid; … 








从 flock 结 构 体 中 可 以 看 出 ， 文 件 锁 的 功能 绝 不 仅仅 局 限于 普通 的 互 
打 锁 ， 它 还 可 以 锁 住 文件 中 的 部 分 内 容 。 但 Nginx 封 装 的 文件 锁 仅 用 于 
保护 代码 段 的 顺序 执行 〈 例 如， 在 进行 负载 均衡 时 ， 使 用 互 斥 锁 保 证 同 
一 时 刻 仅 有 一 个 worker 进 程 可 以 处 理 新 的 TCP 连 接 ) ， 使 用 方式 要 简单 
得 多 : 一 个 lock_file 文 件 对 应 一 个 全 局 互 斥 锁 ， 而 且 它 对 master 进 程 或 
者 worker 进 程 都 生效 。 因 此 ， 对 于 ]_start、]_len、1_pid， 都 填 为 0， 而 
1L_whence 则 填 为 SEEK_SET， 只 需要 这 个 文件 提供 一 个 锁 。L_type 的 值 则 
取 雇 于 用 户 是 想 实现 阻 堵 睡眠 锁 还 是 想 实 现 非 阻塞 不 会 睡眠 的 锁 。 


对 于 文件 锁 ，Nginx 封 装 了 3 个 方法 : ngx_trylock_fd 实 现 了 不 会 阻塞 
进程 、 不 会 使 得 进程 进入 睡眠 状态 的 互 斥 锁 ;，ngx_lock_fd 提 供 的 互 斥 锁 
在 锁 已 经 被 其 他 进程 拿 到 时 将 会 导致 当前 进程 进入 睡眠 状态 ， 直 到 顺利 
拿 到 这 个 锁 后 ， 当 前 进程 才 会 被 Linux 内 核 重 新 调度 ， 所 以 它 是 阻塞 操 
作 ; ngx_unlock_fd 用 于 释放 互 斥 锁 。 下 面 我 们 一 一 列举 它们 的 源 代码 。 





ngx_err_t ngx_trylock_fd(ngx_fd_t fd) 
{ 


struct flock fl1; 
// 这 个 文件 锁 并 不 用 于 锁 文件 中 的 内 容 ， 填 充 为 


fl.1 start = 0; 

f1. 1 len = 0; 

fl.1 pid = 0; 

// F_SETLK 意 味 着 不 会 导致 进程 睡眠 


fl.1 type = F_WRLCK 
fl.1 whence = SEEK_SET， 
// 获取 


fd 对 应 的 互 斥 锁 ， 如 果 返 回 


-41， 则 这 时 的 


ngx_errno 将 保存 错误 码 


if (fcntl(fd, F_SETLK, &f1) == -1) { 
return ngx_errno,; 


return 0; 








使 用 ngx_trylock_fd 方 法 获取 互 斥 锁 成 功 时 会 返回 0， 人 否则 返回 的 其 
实 是 errno 错 误 码 ， 而 这 个 错误 码 为 NGX_EAGAIN 或 者 NGX_EACCESS 
时 表示 当前 没有 拿 到 互 斥 锁 ， 和 否则 可 以 认为 fcnt 执 行 错 误 。 


ngx_lock_fd 方 法 将 会 阻塞 进程 的 执行 ， 使 用 时 需要 非 稼 谨慎 ， 它 可 
能 会 导致 worker 进 程 守 可 睡眠 也 不 人 处理 其 他 正常 请 求 ， 如 下 所 示 。 








x_err_t ngx_lock_fd(ngx_fd_t fd) 
{ 





struct flock fl1; 

fl.1 start = 0; 

fl.1 len = 0; 

fl.1 pid = 0; 

// F_SETLKW 会 导致 进程 睡眠 


fl.1 type = F_WRLCK; 
fl.1 whence = SEEK_SET， 
// 如 果 返 回 


-1， 则 表示 


fcntl1 执 行 错误 。 一 旦 返回 


@， 表 示 成 功 地 拿 到 了 锁 


if (fcntl(fd, F_SETLKW, &f1) == -1) { 
return ngx_errno,; 


return 9; 





只 要 ngx_lock_fd 方 法 返回 0， 就 表示 成 功 地 拿 到 了 互 斥 锁 ， 否 则 就 
古 加 锁 操 作出 现 错误 。 


ngx_unlock fd 方法 用 于 释放 当前 进程 已 经 拿 到 的 互 斥 锁 ， 如 下 所 


钞 。 








ngx_err_t ngx_unlock_fd(ngx_fd_t fd) 
{ 


Struct flock fi1; 
fl.1_ start = 0; 

fl.1 len = 0; 

fl.1 pid = 0; 

// F_UNLCK 表 示 将 要 释放 锁 


fl.1 type = F_UNLCK; 
fl.1 whence = SEEK_SET; 
// 返回 


9 表示 成 功 


if (fcntl(fd, F_SETLK, &f1) == -1) { 
return ngx_errnoy 


return 0; 





当 关 闭 fd 句 柄 对 应 的 文件 时 ， 当 前 进程 将 自动 释放 已 经 拿 到 的 锁 。 


14.8 互 斥 锁 


基于 原子 操作 、 信 号 量 以 及 文件 锁 ，Nginx 在 更 高 层次 封装 了 一 个 
互 斥 锁 ， 使 用 起 来 很 方便 ， 许 多 Nginx 模 块 也 是 更 多 直接 使 用 它 。 下 面 
看 一 下 表 14-1 中 介绍 的 操作 这 个 互 斥 锁 的 5 种 方法 。 


表 14-1 互 斥 锁 的 5 种 操作 方法 


涡 
/< 


方法 名 参 数 
参数 mtx 表示 待 操作 的 ngx_shmtx t 类 型 互 斥 锁 ; 
当 互 斥 锁 由 原子 变量 实现 时 ， 参 数 addr 表示 要 操作 
的 原子 变量 锁 ， 而 互 斥 锁 由 文件 实现 时 ， 参 数 addr 
没有 任何 意义 ; 参数 name 仅 当 互 斥 锁 由 文件 实现 时 
才 有 意义 ， 它 表示 这 个 文件 所 在 的 路 径 及 文件 名 






ngx shmtx create 初始 化 mtx 互 奈 锁 







ngx shmtx destory 参数 mtx 表示 待 操作 的 ngx_shmtx_t 类 型 互 斥 锁 销毁 mtx 互 斥 锁 
无 阻塞 地 试图 获取 互 斥 锁 ， 返 回 
ngx_ shmtx trylock 参数 mtx 表示 待 操作 的 ngx_shmtx t 类 型 互 斥 锁 ”| 1 表示 获取 互 斥 锁 成 功 ， 返回 0 表 


示 获 取 互 斥 锁 失 败 
以 阻塞 进程 的 方式 获取 互 斥 锁 ， 
在 方法 返回 时 就 已 经 持 有 互 斥 锁 了 


ngx_ shmtx unlock 参数 mtx 表示 待 操作 的 ngx_shmtx t 类 型 互 斥 锁 释放 互 斥 锁 


ngx shmtx lock 参数 mtx 表示 待 操作 的 ngx_shmtx t 类 型 互 斥 锁 


表 14-1 中 的 5 种 方法 非常 全 面 ， 获 取 互 斥 锁 时 既 可 以 使 用 不 会 阻塞 
进程 的 ngx_shmtx_trylock 方 法 ， 也 可 以 使 用 ngx_shmtx_lock 方 法 告诉 
Nginx 必 须 持 有 互 斥 锁 后 才能 继续 向 下 执行 代码 。 它 们 都 通过 操作 
ngx_shmtx_t 类 型 的 结构 体 来 实现 互 斥 操作 ， 下 面 再 来 看 一 下 
ngx_shmtx_t 中 有 哪些 成 员 ， 如 下 所 示 。 











typedef struct { 
#if (NGX_HAVE_ATOMIC_OPS) 
// 原子 变量 锁 


ngx_atomic t *lock; 
#if (NGX_HAVE_POSIX_SEM) 
// Semaphore 为 


1 时 表示 获取 锁 将 可 能 使 用 到 的 信号 量 


ngx_uint_t semaphore; 
// Sem 就 是 信号 量 锁 


Sem_t sem; 
#endif 
#else 

// 使 用 文件 锁 时 


fd 表示 使 用 的 文件 句柄 


ngx_fd t fd; 
// name 表 示 文 件 名 


u_char *name 
#endif 
/* 自 旋 次 数 ， 表 示 在 自 旋 状 态 下 等 待 其 他 处 理 器 执行 结果 中 释放 锁 的 时 间 。 由 文件 锁 实 现时 ， 


Spin 没 有 任何 意义 


4 
ngx_uint_t spin; 
} ngx_shmtx_t; 





@ 注意 ”读者 可 能 会 觉得 奇怪 ， 既 然 ngx_shmtx_t 结 构 体 中 的 spin 
成 员 对 于 文件 锁 没 有 任何 意义 ， 为 什么 不 放 在 
#if(NGX_HAVE_ATOMIC_OPS) 宏 内 呢 ? 这 是 因为 ， 对 于 使 用 
ngx_shmtx_t 互 斥 锁 的 代码 来 说 ， 它 们 并 不 想 知道 互 斥 锁 是 由 文件 锁 、 原 
子 变 量 或 者 信号 量 实 现 的 。 同 时 ，spin 的 值 又 具备 非常 多 的 含义 (C 语 


言 的 编程 风格 导致 可 读 性 比 面向 对 象 语言 差 些 ) ， 当 仅 用 原子 变量 实现 
互 斥 锁 时 ，spin 只 表示 自 旋 等 待 其 他 处 理 器 的 时 间 ， 达 到 spin 值 后 就 
会 “让 出 ”当前 处 理 器 。 如 果 spin 为 0 或 者 负 值 ， 则 不 会 存在 调用 PAUSE 
的 机 会 ， 而 是 直接 调用 sched_yield“ 让 出 ”处 理 器 。 假 设 同时 使 用 信号 
量 ，spin 会 多 一 种 含义 ， 即 当 spin 值 为 (ngx_uint D -1 时 ， 相 当 于 告诉 这 
个 互 斥 锁 绝 不 要 使 用 信号 量 使 得 进程 进入 睡眠 状态 。 这 点 很 重要 ， 实 际 
上 ， 在 实现 第 9 章 提 到 的 负载 均衡 锁 时 ，spin 的 值 就 是 (ngx_uint D -1。 


可 以 看 到 ， ngx_shmtx_t 结 构 体 涉 及 两 个 宏 : 
NGX HAVE ATOMIC OPS、NGX HAVE POSIX SEM， 这 两 个 宏 对 
应 着 互 斥 锁 的 3 种 不 同 实现 。 


第 1 种 实现 ， 当 不 文 持 原子 操作 时 ， 会 使 用 文件 锁 来 实现 
ngx_shmtx_t 互 斥 锁 ， 这 时 它 仅 有 fd 和 name 成 员 〈 实 际 上 还 有 spin 成 员 ， 
但 这 时 没有 任何 意义 ) 。 这 两 个 成 员 使 用 14.7 贡 介绍 的 文件 锁 来 提供 阻 
塞 、 非 阻塞 的 互 斥 锁 。 


第 2 种 实现 ， 文 持原 子 操作 却 又 不 文 持 信 号 量 。 





第 3 种 实现 ， 在 文 持 原子 操作 的 同时 ， 操 作 系 统 也 文 持 信号 量 。 


后 两 种 实现 的 唯一 区 别 是 ngx_shmtx_lock 方 法 执行 时 的 效果 ， 也 就 
古 说 ， 文 持 信 号 量 只 会 影响 阻 竖 进程 的 ngx_shmtx_lock 方 法 持 有 锁 的 方 
式 。 当 不 支持 信号 量 时 ，ngx_shmtx_lock 取 锁 与 14.3.3 节 中 介绍 的 自 旋 锁 


是 一 致 的 ， 而 支持 信号 量 后 ，ngx_shmtx_lock 将 在 spin 指 定 的 一 段 时 间 
内 目 旋 等 竺 其 他 处 理 需 杰 放 锁 ， 如 宁 达 到 spin 上 限 还 没有 获取 到 锁 ， 那 
么 将 会 使 用 sem_wait 使 得 当前 进程 进入 睡眠 状态 ， 等 其 他 进程 释放 了 锁 
内 核 后 才 会 唤醒 这 个 进程 。 当 然 ， 在 实际 实现 过 程 中 ，Nginx 做 了 非常 





巧妙 的 设计 ， 它 使 得 ngx_shmtx_lock 方 法 在 运行 一 段 时 间 后 ， 如 果 其 他 
进程 始终 不 放弃 锁 ， 那 么 当前 进程 将 有 可 能 强制 性 地 获得 到 这 把 锁 ， 这 
也 是 出 于 Nginx 不 宜 使 用 阻塞 进程 的 睡眠 锁 方 面 的 考虑 。 


14.8.1 文件 锁 实 现 的 ngx_shmtx_t 锁 


本 节 介 绍 如 何 通 过 文件 锁 实现 表 14-1 中 的 5 种 方法 (也 就 是 Nginx 对 
fcntl 系 统 调用 封装 过 的 ngx_trylock_fd、ngx_lock_fd 和 ngx_unlock_fd 方 法 
实现 的 锁 ) 。 


ngx_shmtx_create 方 法 用 来 初始 化 ngx_shmtx_t 互 斥 锁 ，ngx_shmtx { 
结构 体 要 在 调用 ngx_shmtx_create 方 法 前 先行 创建 。 下 面 看 一 下 该 方法 
的 源 代码 。 





ngx_int_t ngx_shmtx_create(ngx_shmtx_t *mtx, void *addr, u_char *name) 





// 不 用 在 调用 


ngx_shmtx_create 方 法 前 先行 赋值 给 


ngx_shmtx_t 结 构 体 中 的 成 员 


if (mtx->name) { 


/* 如 果 
ngx_shmtx_t 中 的 
name 成 员 有 值 ， 那 么 如 果 与 
name 参 数 相 同 ， 意 味 着 
mtX 互 斥 锁 已 经 初始 化 过 了 ; 否则 ， 需 要 先 销毁 
mtx 中 的 互 斥 锁 再 重新 分 配 


mtx*/ 
If (ngx_strcmp(name, mtx->name) == 0) { 
// 如 果 


name 参 数 与 
ngx_shmtx_t 中 的 


name 成 员 相 同 ， 则 表示 已 经 初始 化 了 


mtx->name = name; 
// 既然 曾经 初始 化 过 ， 证 明 


fd 和 句柄 已 经 打开 过 ， 直 接 返 回 成 功 即 可 
return NGX_OK; 

} 

/* 如 果 
ngx_shmtx_t 中 的 
name 与 参数 
name 不 一 致 ， 说 明 这 一 次 使 用 了 一 个 新 的 文件 作为 文件 锁 ， 那 么 先 调用 
ngx_Sshmtx_destory 方 法 销毁 原文 件 锁 


*/ 
ngx_shmtx_destory(mtx); 


// 按照 


name 指 定 的 路 径 创 建 并 打开 这 个 文件 


mtx->fd = ngx_open_file(name，NGX_FILE_RDWR，NGX_FILE_CREATE_OR_OPEN，NGX_FILE _[ 
if (mtx->fd == NGX_INVALID_FILE) { 
// 一 旦 文件 因为 各 种 原因 (如 权限 不 够 ) 无 法 打开 ， 通 常会 出 现 无 法 运行 错误 








return NGX_ERROR, 


} 
/* 由 于 只 需要 这 个 文件 在 内 核 中 的 
INODE 信 息 ， 所 以 可 以 把 文件 删除 ， 只 要 


fd 可 用 就 行 


*/ 
if (ngx_delete file(name) == NGX_FILE ERROR) { 
mtx->name = name; 
return NGX_OK， 

} 





ngx_shmtx_create 方 法 需要 确保 ngx_shmtx_t 结 构 体 中 的 fd 是 可 用 
的 ， 它 的 成 功 执行 是 使 用 互 斥 锁 的 先决 条 件 。 


ngx_shmtx_destory 方 法 用 于 关闭 在 ngx_shmtx_create 方 法 中 已经 打 
开 的 fd 句柄 ， 如 下 所 示 。 





void ngx_shmtx_destory(ngx_shmtx_t *mtx) 


// 关闭 


ngx_shmtx_t 结 构 体 中 的 


fd 句柄 


if (ngx_close file(mtx->fd) == NGX_FILE ERROR) { 


ngx_log_error(NGX_LOG ALERT, ngx_cycle->log, ngx_errno, 
ngx_close_ file n " \"%s\" failed", mtx->name); 





ngx_shmtx_trylock 方 法 试图 使 用 非 阻 罕 的 方式 获得 锁 ， 返 回 1 时 表 
示 获 取 锁 成 功 ， 返 回 0 表示 获取 锁 失败 。 








ngx_uint_t ngx_shmtx_trylock(ngx_shmtx_t *mtx) 





ngx_err_t err; 
// 由 


14.7 节 介绍 过 的 


ngx_trylock_fd 方 法 实现 非 阻塞 互 斥 锁 的 获取 


err = ngx_trylock_fd(mtx->fd); 
if (err == 0) { 
return 1; 


} 
// 如 果 
err 错 误 码 是 


NGX_EAGAIN， 则 表示 现在 锁 已 经 被 其 他 进程 持 有 了 


if (err == NGX_EAGAIN) { 
return 0; 


ngx_]1og_abort(err，ngx_trylock_fd n " %s failed", mtx->name); 
return ©; 





ngxX_shmtx_lock 方 法 将 会 在 获取 锁 失 败 时 阻塞 代码 的 继续 执行 ， 它 
会 使 当前 进程 处 于 睡眠 状态 ， 等 待 其 他 进程 释放 锁 后 内 核 唤 醒 它 。 可 
见 ， 它 是 通过 14.7 节 介绍 的 ngx_lock_fd 方 法 实现 的 ， 如 下 所 示 。 





void ngx_shmtx_lock(ngx_shmtx_t *mtx) 
ngx_err_t err,; 
// ngx_lock_fd 方 法 返回 


9 时 表示 成 功 地 持 有 锁 ， 返 回 


-1 时 表示 出 现 错误 


err = ngx_lock_fd(mtx->fd); 
if (err == 0) { 
return; 


ngx_l1og abort(err, ngx_lock_ fd _n " %s failed", mtx->name); 





ngx_shmtx_lock 方 法 没有 返回 值 ， 因 为 它 一 旦 返回 就 相当 于 获取 到 
互 斥 锁 了， 这 会 使 得 代码 继续 同 下 执行 。 


ngx_shmtx_unlock 方 法 通过 调用 ngx_unlock_fd 方 法 来 释放 文件 锁 ， 
如 下 所 示 。 





void ngx_shmtx_unlock(ngx_shmtx_t *mtx) 
ngx_err_t err,; 


// 返回 


9 即 表示 释放 锁 成 功 


err = ngx_unlock_fd(mtx->fd); 
if (err == 0) { 
return 


ngx_]1og_abort(err，ngx_unlock_fd_n " %s failed", mtx->name); 





可 以 看 到 ，ngx_shmtx_t 互 斥 锁 在 使 用 文件 锁 实 现时 是 非常 简单 
的 ， 它 只 是 简单 地 封装 了 14.7 节 介绍 的 文件 锁 。 





14.8.2 ”原子 变量 实现 的 ngx_shmtx_t 锁 


当 Nginx 判 断 当 前 操作 系统 文 持 原子 变量 时 ， 将 会 优先 使 用 原子 变 
量 实现 表 14-1 中 的 5 种 方法 〈 即 原子 变量 锁 的 优先 级 高 于 文件 锁 ) 。 不 
过 ， 同 时 还 需要 判断 其 是 否 文 持 信号 量 ， 因 为 文 持 信号 量 后 进程 有 可 能 
进入 睡眠 状态 。 下 面 介 绍 一 下 如 何 使 用 原子 变量 和 信号 量 来 实现 
ngx_shmtx_t 互 斥 锁 ， 注 意 ， 它 比 文件 锁 的 实现 要 复杂 许多 。 




















ngx_shmtx_t 结 构 中 的 lock 原 子 变 量 表示 当前 锁 的 状态 。 为 了 便于 理 

解 ， 我 们 还 是 用 接近 自然 语言 的 方式 来 说 明 这 个 锁 ， 当 lock 值 为 0 或 者 
正 数 时 表示 没有 进程 持 有 锁 ;， 当 lock 值 为 负数 时 表示 有 进程 正 持 有 锁 
(这 里 的 正 、 负 数 仅 相 对 于 32 位 系统 下 有 符号 的 整 型 变量 ) 。Nginx 是 
怎样 快速 判断 lock 值 为 “ 正 数 ” 或 者 “负数 ”的 呢 ? 很 简单 ， 因 为 有 符号 整 
型 的 最 高 位 是 用 于 表示 符号 的 ， 其 中 0 表示 正 数 ，1 表 示 负 数 ， 所 以 ， 在 
确定 整 型 val 是 负数 或 者 正 数 时 ， 可 通过 判断 (val&0x80000000)==0 语 句 
的 真 假 进行 。 

















下 面 看 一 下 初始 化 ngx_shmtx_t 互 斥 锁 的 ngx_shmtx_create 方 法 究竟 
做 了 些 什么 事情 。 





ngx_int_t ngx_shmtx_create(ngx_shmtx_t *mtx, void *addr, u_char *name) 





mtx->lock = addr; 
// 注意 ， 当 


Spin 值 为 


-1 时， 表示 不 能 使 用 信号 量 ， 这 时 直接 返回 成 功 


if (mtx->spin == (ngx_uint t) -1) { 
return NGX_OK， 


} 
// ”spin 值 默认 为 


2048 
mtx->spin 


= 2048; 
// 同时 使 用 信号 量 


#if (NGX_HAVE_POSIX_SEM) 
// 以 多 进程 使 用 的 方式 初始 化 


Sem 信 号 量 ， 


Sem 初 始 值 为 


if (sem init(&mtx->sem, 1, 0) == -1) { 
ngx_log_error(NGX_LOG ALERT, ngx_cycle->log, ngx_errno, 
"sem init() failed"); 
} else { 
// 在 信号 量 初始 化 成 功 后 ， 设 置 


semaphore 标 志 位 为 


1 
mtx->semaphore = 1; 
#endif 
return NGX_OK， 
} 





spin 和 semaphore 成 员 都 将 决定 ngx_shmtx_lock 阻 塞 锁 的 行为 。 


ngx_shmtx_destory 方 法 的 唯一 目的 就 是 释放 信号 量 ， 如 下 所 示 。 





void ngx_shmtx_destory(ngx_shmtx_t *mtx) 


不 
// 支持 信号 量 时 才 有 代码 需要 执行 


#if (NGX_HAVE_POSIX_SEM ) 
/* 当 这 把 锁 的 


Spin 值 不 为 
(ngx_uint_t) -1 时 ， 且 初始 化 信号 量 成 功 ， 
Semaphore 标 志 位 才 为 


1*/ 
if (mtx->semaphore) { 
// 销毁 信号 量 


if (sem destroy(&mtx->sem) == -1) { 
ngx_1log_error(NGX_LOG ALERT, ngx_cycle->log, ngx_errno, "sem destroy()1 


} 
#endif 





以 非 阻塞 方式 获取 锁 的 ngx_shmtx_trylock 方 法 较为 简单 ， 可 直接 判 
断 lock 原 子 变 量 的 值 ， 当 它 为 非 负 数 时 ， 直 接 将 其 置 为 负数 即 表示 持 有 
锁 成 功 。 怎 样 把 0 或 者 正 数 置 为 负数 呢 ? 很 简单 ， 使 用 语句 
vall0x80000000 即 可 把 非 负数 的 val 变 为 负数 ， 这 种 方法 效率 最 高 ， 即 直 


接 修改 val 的 最 高 符号 标志 位 为 1。 

















ngx_uint_t ngx_shmtx_trylock(ngx_shmtx_t *mtx) 


{ 





ngx_atomic uint_t val; 
// 取出 


lock 锁 的 值 ， 通 过 判断 它 是 否 为 非 负 数 来 确定 锁 状态 


val = *mtx->lock; 
/* 如 果 


Val 为 


9 或 者 正 数 ， 则 说 明 没 有 进程 持 有 锁 ， 这 时 调用 


ngx_atomic_cmp_set 方 法 将 


lock 锁 改 为 负数 ， 表 示 当 前 进程 持 有 了 互 斥 锁 


2 
return ((val & 0x80000000) == 0 && 
ngx_atomic_cmp_set(mtx->lock, val, val | 0x80000000 ) ) ; 





@ 注意 (val&0x80000000)==0 是 一 行 语句 ， 而 
ngx_atomic_cmp_set(mtx->lock,val,val |0x80000000) 又 是 一 行 语句 ， 多 进程 
的 Nginx 服 务 将 有 可 能 出 现 虽然 第 1 行 语句 执行 成 功 (表示 锁 未 被 任何 进 
程 持 有 ) ， 但 在 执行 第 2 行 语句 前 ， 又 有 一 个 进程 拿 到 了 锁 ， 这 时 第 2 行 
语句 将 会 执行 失败 。 这 正 是 ngx_atomic_cmp_set 方 法 自身 先 判 断 lock 值 是 
否 为 非 负 数 val 的 原因 ， 只 有 lock 值 为 非 负 数 val， 它 才 会 确定 将 lock 值 赋 
为 负数 val|0x80000000 并 返回 1， 否 则 返回 0 ( 详 见 14.3.2 节 ) 。 


阻塞 式 获 取 互 斥 锁 的 ngx_shmtx_lock 方 法 较为 复杂 ， 在 不 支持 信和 号 
量 时 它 与 14.3.3 市 介绍 的 自 旋 锁 几 乎 完全 相同 ， 但 在 文 持 了 信号 量 后 ， 
它 将 有 可 能 使 进程 进入 睡眠 状态 。 下 面 我 们 分 析 一 下 它 的 操作 步骤 。 





void ngx_shmtx_lock(ngx_shmtx_t *mtx) 
{ 

ngx_uint_t i, n; 

ngx_atomic_ uint_t val; 

// 没有 拿 到 锁 之 前 是 不 会 跳出 循环 的 


Faw > | 
A/*lock 值 是 当前 的 锁 状 态 。 注 意 ， 


oOcK 一 般 是 在 共享 内 存 中 的 ， 它 可 能 会 时 刻 变 化 ， 而 
Val 是 当前 进程 的 栈 中 变量 ， 下 面 代 码 的 执行 中 它 可 能 与 
lock 值 不 一 致 


A 
val = *mtx->lock; 
/* 如 果 


Val 为 非 负数 ， 则 说 明 锁 未 被 持 有 。 下 面试 图 通过 修改 
lock 值 为 负数 来 持 有 和 锁 


*/ 
if ((val & Ox80000000) == 0 
&& Ngx_atomic cmp_set(mtx->lock, val, val | 0x80000000 ) ) 
/* 在 成 功 地 将 
lock 值 由 原先 的 
Val 改 为 非 负 数 后 ， 表 示 成 功 地 持 有 了 和 锁 ， 
ngx_shmtx_lock 方 法 结 来 
*/ 
return; 
} 
// 仅 在 多 处 理 器 状态 下 


Spin 值 才 有 意义 ， 否则 


PAUSE 指 令 是 不 会 执行 的 


if (ngx_ncpu > 1) { 
// 循环 执行 


PAUSE， 检 查 锁 是 否 已 经 释放 


for (n = 1; n < mtx->spin; n <<= 1) { 
// 随 着 长 时 间 没 有 获得 到 锁 ， 将 会 执行 更 多 次 


PAUSE 才 会 检查 锁 
for (i = 0; i < n; i++) { 
// 对 于 多 处 理 器 系统 ， 执 行 


ngx_cpu_pause 可 以 降低 功 耗 


ngx_cpu_pause( ); 


// 再 次 由 共享 内 存 中 获得 


OCkKk 原 子 变 量 的 值 


*mtx->lock; 


JOCK 是 否 已 经 为 非 负数 ， 即 锁 是 否 已 经 被 释放 ， 如 果 锁 已 经 释放 ， 那 么 
JOCK 原 子 变 量 值 设置 为 负数 来 表示 当前 进程 持 有 了 锁 
*/ 


if ((val & Ox80000000) == 0 
&& Ngx_atomic cmp_set(mtx->lock, val, val | 0x80000000 ) ) 


// 持 有 锁 成 功 后 立刻 返回 


return; 


} 
} 
// 支持 信号 量 时 才 继 续 执行 


#if (NGX_HAVE_POSIX_SEM) 
// Semaphore 标 志 位 为 
1 才 使 用 信号 量 


if (mtx->semaphore) { 
// 重新 获取 一 次 可 能 在 共享 内 存 中 的 





ba 
hl 


Jock 原子 变 


val = *mtx->lock; 
// 如 果 


lock 值 为 负数 ， 则 


]ock 值 加 上 


if ((val & OQx80000000) 


&& NgxX_atomic cmp_set(mtx->lock, val, val + 1)) 


/* 检 查 信号 量 


Sem 的 值 ， 如 果 


Sem 值 为 正 数 ， 则 


Sem 值 减 


1， 表 示 拿 到 了 信号 量 互 斥 锁 ， 同 时 


Sem_wait 方 法 返回 


上 。 如 果 


Sem 值 为 


0 或 者 负数 ， 则 当前 进程 进入 睡眠 状态 ， 等 待 其 他 进程 使 用 


ngx_shmtx_unlock 方 法 释放 锁 (等 待 


Sem 信 号 量变 为 正 数 ) ， 到 时 


Linux 内 核 会 重新 调度 当前 进程 ， 继 续 检 查 





Sem 值 是 否 为 正 ， 重 复 以 上 流程 


WA 
while (sem wait(&mtx->sem) == -1) { 
ngx_err_t err; 
err = ngx_errno; 
// 当 


EINTR 信 号 出 现时 ， 表 示 


Sem_wait 只 是 被 打 断 ， 并 不 是 出 错 


if (err != NGX_EINTR) { 
break; 


} 
} 
// 循环 检查 


lock 锁 的 值 ， 注 意 ， 当 使 用 信号 量 后 不 会 调用 


sched_yield 
continue,; 


#endif 
// 在 不 使 用 信号 量 时 ， 调 用 


sched_yield 将 会 使 当前 进程 暂时 “让 出 ”处 理 器 
ngx_sched_yield(); 


} 
} 





可 以 看 到 ， 在 不 使 用 信号 量 时 例如, NGX_HAVE_POSIX_SEM 
宏 没 打开 ， 或 者 spin 的 值 为 ngx_uint_D-1) ，ngx_shmtx_lock 方 法 与 
ngx_spinlock 方 法 非 第 相似 ， 而 在 使 用 信号 量 后 将 会 使 用 可 能 让 进程 进 
入 睡眠 的 sem_wait 方 法 代替 “让 出 ?处理 器 的 ngx_sched_yield 方 法 。 这 里 
不 建议 在 Nginx worker 进 程 中 使 用 带 信号 量 的 ngx_shmtx_lock 取 锁 方 
2 





ngx_shmtx_unlock 方 法 会 释放 锁 ， 虽 然 这 个 释放 过 程 不 会 了 蛆 寨 进 
程 ， 但 设置 原子 变量 lock 值 时 是 可 能 失败 的 ， 因 为 多 进程 在 同时 修改 


lock 值 ， 而 ngx_atomic_cmp_set 方 法 要 求 参 数 old 的 值 与 lock 值 相同 时 才 
能 修改 成 功 ， 因 此 ，ngx_atomic_cmp_set 方 法 会 在 循环 中 反复 执行 ， 直 
到 返回 成 功 为 止 。 该 方法 的 实现 如 下 所 示 : 





void ngx_shmtx_unlock(ngx_shmtx_t *mtx) 


{ 
ngx_atomic uint t val, old, wait,; 
// 试图 循环 重 置 


lock 值 为 正 数 ， 此 时 务必 将 互 斥 锁 释 放 


for ( ;; ) 
// 由 共享 内 存 中 的 


Lock 原 子 变 量 取 出 锁 状 态 


old = *mtx->lock; 
// 通过 把 最 高 位 置 为 


0，, 将 

Jock 变 为 正 数 
wait = old & QOx7fffffff; 
// 如 果 变 为 正 数 的 

]oCKk 不 是 

0， 则 减 去 

1 


val = wait wait - 1 : 0; 
// 将 


lock 锁 的 值 设 为 非 负 数 


val 
If (ngx_atomic_ cmp_set(mtx->lock, old, val)) { 
// 设置 锁 成 功 后 才能 跳出 循环 ， 否 则 将 持续 地 试图 修改 


lock 值 为 非 负数 


break ; 


} 
} 
#if (NGX_HAVE_POSIX_SEM) 
/* 如 果 
lock 锁 原先 的 值 为 
@， 也 就 是 说 ， 并 没有 让 某 个 进程 持 有 锁 ， 这 时 直接 返回 ; 或 者 ， 


Semaphore 标 志 位 为 


9， 表 示 不 需要 使 用 信号 量 ， 也 立即 返回 


WA 
If (wait == 0 || !mtx->semaphore) { 
return; 
} 
/* 通 过 


Sem_post 将 信号 量 


Sem 加 


1， 表 示 当 前 进程 释放 了 信号 量 互 斥 锁 ， 通 知 其 他 进程 的 


Sem_wait 继 续 执 行 


2 
if (sem post(&mtx->sem) == -1) 
ngx_l1og_error(NGX_ LOG ALERT, ngx_cycle->log, ngx_errno, 
"Sem_post() failed while wake shmtx"); 
} 
#endif 
} 








由 于 原子 变量 实现 的 这 5 种 互 斥 锁 方 法 是 Nginx 中 使 用 最 广泛 的 同步 
方式 ， 当 需要 Nginx 文 持 数 以 万 计 的 并 发 TCP 请 求 时 ， 通 第 都 会 把 spin 值 


设 为 gx_uint_0D-1。 这 时 的 互 斥 锁 在 取 锁 时 都 会 采用 目 旋 锁 ， 对 于 
Nginx 这 种 单 进程 处 理 大 量 请 求 的 场景 来 说 是 非常 适合 的 ， 能 够 大 量 
低 不 必要 的 进程 间 切 换 带 来 的 消耗 。 














全 9 小 于 








Nginx 古 一 个 能 够 并 友 处 理 儿 十 万 其 至 几 百 万 个 TCP 连 接 的 高 性 能 
服务 器 ， 因 此 ， 在 进行 进程 间 通 信 时 ， 必 须 充分 考虑 到 不 能 过 分 影响 正 
常 请 求 的 处 理 。 例 如 ， 使 用 14.4 节 介绍 的 套 接 字 通 信 时 ， 套 接 字 部 被 设 
为 了 无 阻 豆 模式 ， 防 止 执行 时 阻塞 了 进程 导致 其 他 请 求 得 不 到 处 理 ， 又 
如 ，Nginx 封 装 的 锁 都 不 会 直接 使 用 信号 量 ， 因 为 一 旦 获取 信和 号 量 互 斥 
锁 失 败 ， 进 程 就 会 进入 睡眠 状态 ， 这 会 导致 其 他 请 求 “ 饿 死 ”。 








当 用 户 开 发 复杂 的 Nginx 模 块 时 ， 可 能 会 涉及 不 同 的 worker 进 程 间 
通信 ， 这 时 可 以 从 本 章 介绍 的 进程 间 通 信 方 式 上 进行 选择 ， 从 使 用 上 
说 ，ngx_shmtx _t 互 斥 锁 和 共享 内 存 应 当 是 第 三 方 Nginx 模 块 最 稼 用 的 进 
程 间 通信 方式 了 ，ngx_shmtx_t 互 斥 锁 在 实现 中 充分 考虑 了 是 否 引发 睡 
眼 的 问题 ， 用 户 在 使 用 时 需要 明确 地 判断 出 是 否 会 引发 进程 睡眠 。 当 
然 ， 如 果 不 使 用 Nginx 封 装 过 的 进程 间 通 信 方 式 ， 则 需要 注意 跨 平台 ， 


以 及 是 人 否 会 阻塞 进程 的 运行 等 问题 。 














第 15 间 ”变量 


Nginx 有 许多 功能 体现 在 nginx.conf 这 个 脚本 式 的 配置 文件 里 ， 这 些 
0 

， 并 没有 什么 统一 的 标准 ， 这 在 第 4 章 已 经 提 及 。 然 而 ， 我 们 可 以 看 
到 许多 广 为 流传 的 配置 项 ， 它 们 都 文 持 在 一 行 配置 中 ， 加 入 详 如 $ 符 扎 
紧 跟 字 符 串 的 方式 ， 试 图 表达 实时 请 求 中 某 些 共性 参数 ， 就 像 编程 语言 
中 的 变量 与 值 ， 这 使 得 Nginx 的 使 用 成 本 、 学 习 成 本 大 幅 降低 ，Nginx 用 
户 仅 在 nginx.conf 中 做 些 修改 就 可 以 拥有 更 复 条 的 功能 














例如 在 指定 access.log 请 求 访问 日 志 格 式 的 时 候 ， 
ngx_http_log_module 模 块 就 允许 Nginx 管 理 员 非常 灵活 地 定义 日 志 格 
式 ， 以 方便 诸如 awstats 等 第 三 方 统计 工具 能 够 依据 个 性 化 的 日 志 为 站 长 
们 分 析出 有 意义 的 结果 来 ， 例 如 : 








Jog_format main ,remote_ addr $remote user ' 

" [$time_ local] "$request" $status ' 
,$host $body_bytes_sent $gzip_ratio "S$http.. referer" : 
'"$http_user_agent" "$http x_ forwarded_ for 

access_log logs/access.log main; 





又 比如 ， 在 限制 用 户 的 请 求 访问 速度 时 ， 怎 样 判断 不 同 的 TCP 连 接 
是 来 自 于 同一 用 户 的 请 求 呢 ? 有 些 场景 是 依据 TCP 连 接 的 对 端 卫 ， 但 如 
果 客 户 端 是 通过 代理 服务 器 访问 则 又 不 可 靠 。 还 有 些 场 景 会 依据 http 头 





部 的 cookie， 甚 至 更 小 众 的 需求 可 以 依据 URI 或 者 URL 参 数 。 
ngx_http_limit_ req_module 模 块 提 供 这样 复 洒 的 功能 以 满足 广泛 的 场 

景 ， 所 依据 的 也 是 在 nginx.conf 配 置 文件 中 提供 $ 这 样 的 配置 项 以 描述 请 
求 ， 比 如 可 以 依据 对 端正 进行 限 速 


limit_req_zone $binary_remote addr zone=one:10m rate=1r/s; 





在 这 两 个 例子 中 ， 其 实 都 是 在 模块 中 使 用 Nginx 定 义 的 内 部 变量 ， 
像 $remote_addr 这 样 的 参数 。 这 些 内 部 变量 在 Nginx 官 方 代 码 中 定义 ， 目 
前 是 在 ngx_http_variables.c 文 件 的 ngx_http_core_variables 数 组 中 定义 
的 。 在 本 章 中 ， 我 们 首先 学 习 如 何在 自己 的 模块 中 使 用 已 有 的 常用 内 部 
变量 ， 使 模块 具备 类 似 access_log 或 者 limit_req 模 块 在 nginx.conf 文 件 中 
配置 内 部 变量 的 功能 





除了 要 能 够 使 用 己 有 变量 外 ， 我 们 还 需要 具备 定义 新 的 内 部 变量 的 
能 力 ， 使 其 他 Nginx 模 块 也 能 够 使 用 我 们 定义 的 新 变量 。 这 些 新 变量 与 
现 有 的 内 部 变量 是 一 致 的 ， 也 是 在 使 用 到 的 时 候 开 始 解析 、 绥 存 。 





官方 的 ngx_http_rewrite_module 模 块 还 提供 了 配置 文件 脚本 式 语法 
的 执行 ， 允 许 在 配置 文件 里 直接 定义 全 新 的 变量 ， 由 于 它 不 在 代码 中 而 
是 在 nginx.conf 中 定义 ， 所 以 称 其 为 外 部 变量 ， 例 如 : 





set $parameter1 "abcd" 
set $memcached_key ' 9 








本 章 将 移 以 一 个 简洁 的 例子 描述 使 用 变量 的 基本 开发 方法 ， 再 通过 
说 明 Nginx 对 变量 的 实现 原理 使 读者 更 透彻 地 理解 这 种 开 友 方式 ， 进 而 
再 扩展 这 个 例子 ， 帮 助 读者 更 灵活 地 掌握 变量 的 使 用 。 最 后 ， 则 会 以 一 
个 简单 的 外 部 变量 配置 为 例 ， 介 绍 脚本 引擎 是 怎样 编译 、 执 行 脚 本 指令 
的 。 








15.1 ”使 用 内 部 变量 开发 模块 





使 用 Nginx 预 定义 的 内 部 变量 的 方法 非常 简单 ， 将 你 需要 使 用 的 变 
量 名 作为 参数 传 入 《例如 在 解析 配置 文件 的 时 候 ) ， 调 用 
ngx_http_get_variable_index 方 法 ， 获 取 到 这 个 变量 名 对 应 的 索引 值 ， 如 








有 
字符 串 ngx_str_ t 类 型 的 name 就 是 变量 名 ， 这 个 变量 名 必须 是 某 个 

Nginx 模 块 定 义 过 的 ， 返 回 值 就 是 这 个 变量 的 索引 值 。 关 于 变量 的 索引 
在 15.2 市 再 详细 说 明 ， 通 常 来 说 ， 使 用 索引 值 而 不 是 变 量 字 符 串 来 获取 
变量 值 是 个 好 主意 ， 它 会 加 快 Nginx 的 执行 速度 。 事 实 上 ，Nginx 提 供 了 
两 种 方式 来 找 出 要 使 用 的 内 部 变量 ， 一 种 是 索引 过 的 变量 ， 可 直接 由 数 
组 下 标 找 到 元 素 ， 另 一 种 是 添加 到 散 列表 的 变量 ， 需 要 将 字符 串 变 量 名 
由 散 列 方法 算出 散 列 值 ， 再 从 散 列 表 中 找 出 元 素 ， 遇 到 元 系 冲 突 时 需要 
遍历 开 散 列表 的 槽 位 链表 〈 人 参见 第 7 章 ) 。 可 见 ， 哪 个 更 快 是 一 目 了 然 
的 ， 当 然 ， 索 引 变 量 要 比 散 列 变量 占用 多 一 点 的 内 存 。 


























保存 这 个 索引 值 〈“ 例 如 在 你 的 配置 结构 体 中 ) 。 处 理 请 求 时 ， 则 使 
用 这 个 索引 值 ， 调 用 ngx_http_get_indexed_variable 方 法 获取 到 变量 的 





值 ， 如 下 : 





ngx_http_variable value t 
ngx_http_get_indexed a http_request_t *r, ngx_uint_t index) 








index 参 数 就 是 ngx_http_get_variable_index 方 法 获得 的 变量 索引 ， 而 
I 参数 当然 束 是 请 求 了 ， 每 一 个 变量 的 值 都 随 着 请 求 的 不 同 而 变化 。 方 
法 的 返回 值 束 是 变量 值 ， 当 然 返回 NULL 即 没有 解析 出 变量 。 





最 基本 的 使 用 变量 方法 就 是 如 此 简单 ， 我 们 移 不 探 完 更 灵活 的 使 用 
方式 和 数据 成 员 的 详细 意义 ， 移 以 一 个 可 运行 的 例子 来 给 不 热 悉 的 读者 
朋友 一 个 直观 的 认识 。 


在 配置 文件 中 使 用 变量 可 以 提高 模块 功能 的 灵活 性 ， 也 是 Nginx 模 
块 的 常用 手法 。 就 如 第 4 章 所 述 ，nginx.conf 中 的 配置 项 格式 如 何 设计 完 
全 是 模块 的 自由 ， 即 使 把 配置 项 设计 得 无 比 另类 也 不 影响 我 们 使 用 内 部 
变量 。 然 而 ， 符 合 惯例 的 设计 会 降低 使 用 、 维 护 成 本 ， 因 此 ， 最 好 还 是 
在 配置 文件 中 使 用 变量 时 在 变量 名 前 加 上 “$” 符 号 。 本 节 的 这 个 例子 将 
实现 以 下 功能 : 在 配置 文件 中 指定 某 些 location 下 的 请 求 来 临时 ， 必 须 
根据 配置 项 myallow 指 定 的 变量 及 其 判定 值 来 决定 请 求 是 否 被 允许 。 比 
如 ， 如 果 在 nginx.conf 中 加 入 下 面 这 段 配 置 ， 这 个 模块 就 会 通过 myallow 
选项 决定 某 些 请 求 必须 具备 testHeader:xxx 这 样 的 http 头 部 才能 放行 ， 有 
些 请 求 则 必须 来 自 于 IP 10.69.50.199 才 能 放行 ， 只 要 是 Nginx 定 义 的 内 部 
变量 都 可 以 放 在 myallow 中 。 




















| 


location /test1 { 
myallow $http_testHeader xxx; 
root /www/test1; 


} 
Jocation /test2 { 
root /www/test2; 


location / { 

root /Www; 

myallow $remote addr 10.69.50.199; 
} 





当 ]ocation 内 的 请 求 到 达 时 ，myallow 配 置 将 会 在 
NGX_HTTP_ACCESS_PHASE 阶 段 产生 作用 ， 当 具备 相应 的 如 $varaible 
内 部 变量 ， 且 其 值 为 myallow 的 第 2 个 参数 时 ， 这 个 请 求 才 能 继续 进行 ， 
否则 返回 403 错 误 码 。 


笔者 构造 这 个 例子 虽然 试图 简单 到 只 使 用 http 内 部 变量 ， 却 仍然 使 
用 到 了 第 4 章 的 配置 项 解析 、 第 11 章 的 HTTP 访 问 控 制 阶 段 ， 读 者 阅读 时 
大 有 疑问 可 翻阅 这 两 章 回 顾 。 








15.1.1 定义 模块 


这 次 把 模块 名 取 为 ngx_http_testvariable_module， 通 过 config 配 置 文 
件 把 模块 编译 进 Nginx 的 方法 参见 第 3 草 ， 这 一 小 市 仅 定 义 表 示 模 块 的 数 
据 结 构 ， 如 下 : 











ngx_module t ngx_http_testvariable module = 





NGX_MODULE_V1, 

&ngx_http_testvariable module ctx, 
ngx_http_testvariable_ commands, 

NGX_HTTP_MODULE， /* module type */ 


NULL, /* init master */ 


NULL， /* init module */ 
NULL， /* init process */ 
NULL, /* init thread */ 
NULL, /* exit thread */ 
NULL， /* exit process */ 
NULL， /* exit master */ 


NGX_MODULE_V1_PADDING 
}; 





这 个 模块 是 一 个 普通 http 模 块 ， 所 以 不 需要 在 通用 的 master、worker 
进程 启动 过 程 中 引入 回调 方法 ， 而 是 在 ngx_http_testvariable _ module_ctx 
中 决定 了 在 http{} 配 置 解析 时 的 调用 方式 ，15.1.2 节 会 描述 这 一 结构 体 的 
定义 。ngx_http_testvariable_commands 描 述 了 模块 如 何 解析 配置 项 ， 在 
15.1.3 节 会 详细 描述 


15.1.2 ”定义 http 模 块 加 载 方 式 


ngx_http_testvariable_module_ctx 的 定义 如 下 : 





static ngx_http_module t ngx_http_testvariable module ctx = 





// 不 需要 在 解析 配置 项 前 做 些 什 么 。 如 果 需 要 添加 新 变量 ， 则 必须 在 这 个 回调 方法 中 实现 


NULL， /* preconfiguration */ 
// 解析 配置 完毕 后 会 回调 


ngx_http_mytest_init 
ngx_http_mytest_init, /* postconfiguration */ 
// myallow 配 置 不 能 存在 于 


http{} 和 


Server{} 配 置 下 ， 所 以 通常 下 面 这 


4 个 回调 方法 不 用 实现 


NULL, /* create main configuration */ 


NULL, /* init main configuration */ 
NULL, /* create server configuration */ 
NULL, /* merge server configuration */ 
// 生成 存放 
location 下 
myallow 配 置 的 结构 体 
ngx_http_mytest_create_loc_conf, /* create location configuration */ 





// 因为 不 存在 合并 不 同 级 别 下 冲突 的 配置 项 的 需求 ， 所 以 不 需要 





merge 方 法 


NULL /* merge Location configuration */ 


}; 





Y 


这 个 定义 表明 ，http 配 置 项 解析 完毕 后 需要 调用 ngx_http_mytest_init 
方法 ， 因 为 在 这 个 方法 中 ， 我 们 将 会 把 ngx_http_testvariable_module 模 块 
加 入 到 请 求 的 处 理 流程 中 ;而 ngx_http_mytest_create_loc_conf 回 调 方 法 
负责 生成 存储 配置 的 ngx_myallow_loc_conf t 结 构 体 : 








typedef struct { 


// 变量 


variable 的 索引 值 


int variable_index; 
// myallow 配 置 后 第 


1 个 参数 ， 表 示 待 处 理 变量 名 


ngx_str_t variable; 
// myallow 配 置 后 第 


2 个 参数 ， 表 示 变 量 值 必须 为 


equalvalue 才 能 放行 请 求 


ngx_str_t equalvalue 
} ngx_myallow_loc_conf_t,; 











ngx_http_mytest_create_loc_conf 方 法 只 是 负责 在 每 个 location 下 生成 


ngx_myallow_loc_conf t 结 构 体 ， 所 以 一 如 既往 的 简单 : 





static void * 
ngx_http_mytest_create_loc _ conf(ngx_conf_t *cf) 





ngx_myallow_loc conf_t *conf; 
conf = ngx_pcalloc(cf->pool, sizeof(ngx_myallow loc_conf_t)); 
if (conf == NULL) { 

return NULL; 


} 
// 没有 出 现 
myallow 配 置 时 


variable _index 成 员 为 


-1 
conf->variable_index = -1; 
return conf; 





ngx_http_mytest_init 方 法 用 来 把 处 理 请 求 的 方法 
ngx_http_mytest_handler 加 入 到 Nginx 的 11 个 HTTP 处 理 阶 段 中 ， 由 于 我 
们 是 需要 控制 请 求 的 访问 权限 ， 因 此 会 把 它 加 入 到 
NGX_HTTP _ACCESS PHASE 阶段 中 ， 如 下 : 








static ngx_int_t 
ngx_http_mytest_init(ngx_conf_t *cf) 


ngx_http_handler_pt *h; 
ngx_http_core_ main conf_t *cmcf,; 
// 取出 全 局 唯一 的 核心 结构 体 





ngx_http_core main conf_t 
cmcf = ngx_http_conf_get module main conf(cf, ngx_http_core module); 


// 在 








cmcf->phases[NGX_HTTP_ACCESS_PHASE] 阶段 添加 处 理 方 法 


h = ngx_array_push(&cmcf->phases[NGX_HTTP_ACCESS_ PHASE] ,handlers ) ， 
if (h == NULL) { 
return NGX_ERROR,; 


} 
// 处 理 请 求 的 方法 是 本 模块 的 


ngx_http_mytest_handler 方 法 


*h = ngx_http_mytest_handler; 
return NGX_OK， 





15.1.3 ”解析 配置 中 的 变量 


解析 配置 项 的 ngx_http_testvariable_commands 数 组 定义 如 下 : 





static ngx_command t ngx_http_testvariable commands[] = 
{ 
{ 
ngx_string("myallow"), 
// 配置 项 只 能 存在 于 


location 内 ， 且 只 能 有 


2 个 参数 


NGX_HTTP_LOC_CONF | NGX_CONF_TAKE2, 
ngx_http_myallow, 
NGX_HTTP_LOC_CONF_OFFSET, 

9, 





NULL 


了 
ngx_null command 


}; 





解析 myallow 配 置 项 时 完全 没有 使 用 预 置 的 解析 方法 ， 全 靠 新 定义 
的 ngx_http_myallow 方 法 。 由 于 我 们 把 配置 项 定义 为 : 





myallow $remote addr 10.69.50.199; 





所 以 ， 解 析 时 第 1 个 参数 需要 确认 第 1 个 字符 必须 是 以 “$” 符 号 开 
始 ， 之 后 的 字符 串 必须 是 一 个 已 经 定义 的 变量 ， 第 2 个 参数 则 做 普通 字 


符 串 处 理 ， 如 下 : 








static char * 
ngx_http_myallow(ngx_conf_t * cf, ngx_command t * cmd, void * conf) 


ngx_str_t *value; 
ngx_myallow_loc _ conf_t *macf = conf,; 
value = cf->args->elts,; 

// myallow 只 会 有 


2 个 参数 ， 加 上 其 自身 ， 
cf->args 应 有 


3 个 成 员 


if (cf->args->nelts != 3) { 
return NGX_CONF_ERROR, 

} 

// 第 


1 个 参数 必须 是 


$ 打 头 的 字符 囊 


if (value[1i].data[0] == '$') { 
// 去 除 第 


Value[1] 就 是 变量 名 


value[1].len--; 
value[1].datat+t++; 
// 获取 变量 名 在 


Nginx 中 的 索引 值 ， 加 速 访问 


macf->variable index = ngx_http_get variable index(cf, &value[1]); 
If (macf->variable index == NGX_ ERROR) { 
return NGX_CONF_ERROR, 
} 
macf->variable = value[1]; 
} else { 
return NGX_CONF_ERROR, 


} 
// 保存 
myallow 的 第 


2 个 参数 


macf->equalvalue= value[2]; 
return NGX_CONF_OK,; 





这 样 ， 每 个 location 下 都 有 的 ngx_myallow_loc_conf t 结 构 体 就 存放 
了 可 能 存在 的 这 两 个 参数 ， 留 待 处 理 请 求 时 使 用 。 





15.1.4 ”处 理 请 求 


ngx_http_mytest_init 方 法 已 经 决定 http 请 求 到 达 Nginx 后 ， 将 会 在 
NGX_HTTP_ACCESS_PHASE 阶 段 按 照 模块 顺序 调用 到 这 个 自 定义 的 
ngx_http_mytest_handler 方 法 。 在 这 个 方法 中 ， 我 们 首先 需要 取出 请 求 
选用 的 location 下 的 ngx_myallow_loc_conf t 结 构 体 ， 它 表明 了 location 下 
是 否 具 有 myallow 配 置 项 一 一 这 由 variable_index 是 否 为 -1 决定 。 接 着 ， 
调用 ngx_http_get_indexed_variable 方 法 取出 做 了 索引 的 变量 ， 再 比较 变 
量 的 值 是 否 与 equalvalue 字 符 串 完全 相同 ， 若 相同 则 权限 判断 阶段 通 
过 ， 人 否则 返回 403 拒 绝 请 求 。 方 法 实现 如 下 : 

















static ngx_int_t ngx_http_mytest_handler(ngx_http_request _t *r) 
{ 





ngx_myallow_loc conf_t *conf; 
ngx_http_variable_value t *VV; 
// 先 取 到 当前 


location 下 本 模块 的 配置 项 存储 结构 体 


conf = ngx_http_get_ module loc conf(r, ngx_http_testvariable module); 
if (conf == NULL) { 
return NGX_ERROR; 





} 
// 如 果 
location 下 没有 


myallow 配 置 项 ， 放 行 请 求 


if (conf->variable index == -1) { 
return NGX_DECLINED ; 


} 
// 根据 索引 过 的 


Variable_index 下 标 ， 快 速 取得 变量 值 


VV 
vv = ngx_http_get_indexed_ variable(r, conf->variable_ index); 


if (vv == NULL || vv->not_found) { 
return NGX_HTTP_FORBIDDEN,; 


conf->equalvalue 相 同 ， 完 全 相同 才 会 放行 请 求 


if (vv->len == conf->equalvalue.len && 
0 == ngx_strncmp(conf->equalvalue.data,vv->data,vv->len)) { 
return NGX_DECLINED ， 


// 否则 ， 返 回 


403 拒 绝 请 求 继续 向 下 执行 


return NGX_HTTP_FORBIDDEN, 





如 此 ， 这 个 简单 的 模块 就 开发 完成 了 。 这 个 例子 很 简单 ， 仅 用 于 快 
速 上 手 ， 使 用 变量 的 更 多 功能 前 我 们 必须 先 理 清 变量 工作 的 原理 。 


15.2 ”内 部 变量 工作 原理 


理解 内 部 变量 的 设计 要 从 其 应 用 场景 入 手 。 顾 名 思 义 , “内 部 ?变量 
古 在 Nginx 的 代码 内 部 定义 的 ， 也 就 是 说 ， 它 是 由 Nginx 模 块 在 C 代 码 中 
定义 的 。 读 者 对 C 语 言 应 该 是 比较 熟悉 的 ， 变 量 通 常 有 “声明 ”“ 定 
义 ”“ 赋 值 人 “使 用 ”这 4 个 阶段 ， 而 上 面 所 说 的 定义 ， 实 际 上 更 像 是 C 
语言 里 的 声明 ， 为 什么 呢 ? 因 为 现在 只 是 说 明 有 这 么 一 个 变量 ， 而 没有 
实际 分 配 用 于 存储 变量 值 的 内 存 。 什 么 时 候 分 配 存 储 变量 值 的 内 存 空 间 
呢 ? 只 有 对 变量 赋值 的 时 候 ! 这 有 两 个 原因 ， 一 是 变量 值 的 大 小 是 不 确 
定 的 ， 提 前 分 配 会 导致 内 存 浪费 或 者 不 必要 的 内 存 拷贝 ， 二 是 一 个 变量 
可 能 在 很 多 场景 的 请 求 中 是 得 不 到 使 用 的 ， 提 前 分 配 是 不 必要 的 。 接 
者 ，Nginx 框 架 会 从 性 能 的 角度 考虑 ， 将 所 有 内 部 变量 生成 散 列 表 ， 同 
时 也 允许 各 个 模块 将 它们 各 目 需 要 的 变量 索引 到 一 个 数组 中 ， 加 快 访问 
速度 。 























在 请 求 到 来 时 ，Nginx 对 变量 的 赋值 通常 是 采取 “用 时 赋值 ”的 策 
略 ， 也 就 是 说 ， 只 有 妆 茶 个 模块 试图 取 变 量 的 值 时 才 会 对 变量 进行 赋 
值 ， 而 不 是 接收 了 完整 的 HTTP 尖 部 后 就 开始 解析 变量 。 当 然后 者 这 
种 提前 赋值 更 符合 直观 理解 ， 但 是 绝 大 部 分 变量 就 是 这 么 设计 的 ， 为 什 
么 呢 ? 因为 Nginx 是 一 个 极度 追求 性 能 、 应 用 场景 单一 的 平台 ， 它 主要 
用 于 Web 前 端 ， 许 多 Nginx 横 块 各 目 负 责 着 不 同 的 请 求 ， 因 此 ， 对 于 每 

















个 请 求 都 去 解析 一 过 所 有 的 变量 ， 这 个 代价 就 有 些 大 了 ， 反 而 是 对 于 
个 请 求 而 言 ， 首 次 使 用 一 个 变量 时 才 去 解析 、 给 它 赋值 、 绥 存 变量 值 ， 
之 后 就 直接 取 缓 存 值 ， 这 种 方式 性 能 高 得 多 ， 有 点 像 Linux 进 程 fork 时 
的 “copy on write"， 原 因 都 是 一 个 请 求 多 半 只 使 用 全 部 变量 的 一 小 部 


分 。 














使 用 变量 时 ，Nginx 提 供 了 两 种 方式 找到 变量 : 一 是 根据 索引 值 下 
接 找 到 数组 里 的 相应 变量 ， 二 是 根据 变量 名 字符 串 hash 出 的 散 列 值 ， 依 
据 散 列表 找到 相应 的 变量 。 没 有 第 3 种 方式 ， 因 此 ， 如 果 我 们 定义 了 一 
个 变量 ， 但 设 定 为 不 能 hash 进 入 散 列 表 ， 同 时 ， 使 用 该 变量 的 模块 义 没 
有 把 它 加 入 索引 数组 ， 那 么 这 个 变量 是 无 法 使 用 的 。 




















15.2.1 何 时 定义 变量 


开发 Nginx 模 块 时 ， 什 么 时 候 、 在 哪个 回调 方法 里 定义 变量 呢 ? 这 
当然 不 是 随意 的 ， 因 为 变量 的 赋值 等 许多 工作 都 是 由 Nginx 框 架 来 做 
的 ， 所 以 Nginx 的 HITP 框 架 要 求 : 所 有 的 HTTP 模 块 都 必须 在 
ngx_http_module_t 结 构 体 中 的 preconfiguration 回 调 方法 中 定义 新 的 变 
量 。 为 什么 要 在 这 里 定义 变量 呢 ? 我 们 回顾 第 10 章 HITP 框 架 的 初始 化 
流程 ， 图 10-10 为 了 使 主流 程 更 清晰 忽略 了 变量 的 处 理 ， 我 们 从 图 10-10 
中 第 3 步 创 建 配置 结构 体 开始 ， 给 出 变量 的 初始 化 流程 图 ， 如 图 15-1 所 


钞 。 








简单 解释 图 15-1 里 各 个 步骤 与 变量 间 的 关系 : 


1) 调用 各 HTTP 模 块 的 create_(main/src/loc)_conf 方 法 ， 用 于 第 3 步 
解析 配置 项 时 存放 配置 参数 。 也 得 有 个 地 方 存 放 配 置 文 件 中 的 变量 名 或 
者 索引 ! 


2) 按照 所 有 HTTP 模 块 的 顺序 ， 调 用 它们 的 preconfiguration 方 法 
《如 果实 现 的 话 ) 。 要 想 定义 变量 ， 这 是 唯一 的 机 会 。 


1 ) 调用 各 HTTP 模 块 的 create_(main/src/loc)_con{ 方 法 用 于 存放 解析 出 的 配置 项 


2 ) 调用 各 HTTP 模 块 的 preconfiguration 方 法 ， 可 引入 新 变量 


2.1 ) ngx_http_core_module 模 块 在 这 一 步 中 添加 ngx_http_core_variables 核 心 变量 


2.2 ) 其 他 模块 依次 在 preconfiguration 方 法 中 可 能 加 入 新 的 变量 


3 ) 开始 解析 、 处 理 http{...} 块 下 的 所 有 配置 项 


3.1 ) 各 模块 解析 配置 的 方法 中 ， 可 能 会 将 某 个 变量 索引 化 


4) 依次 调用 HTTP 模 块 的 postconfiguration 方 法 使 模块 介入 HTTP 处 理 阶段 中 


5 ) 调用 ngx_http_variables_init_vars 方 法 初始 化 所 有 变量 


5.1 ) 检查 索引 变量 的 合法 性 ， 并 设置 其 解析 方法 


5.2 ) 初始 化 索引 过 的 http_、sent_http_、upstream_http_、cookie_、arg_ 变 量 


5.3 ) 将 需要 散 列 的 变量 构造 出 静态 散 列表 





S 


图 15-1 HTTP 变量 的 初始 化 


2.1) HTTP 模 块 中 ，ngx_http_core_module 模 块 是 排名 第 1 的 ， 所 以 
会 首先 执行 它 的 preconfiguration 方 法 (实际 为 


ngx_http_core_preconfiguration 方 法 ): 





static ngx_http_module t ngx_http_core module ctx = { 
ngx_http_core_preconfiguration, /* preconfiguration */ 


}; 











而 这 个 方法 中 其 实 就 干 了 一 件 事 : 调用 
ngx_http_variables_add_core_vars 方 法 ， 把 用 于 存放 变量 的 结构 体 初 始 
化 ， 再 将 Nginx 核 心 变量 加 入 准备 hash 的 数组 variables_keys 中 。 核 心 变 
量 可 以 在 http://nginx.org/cn/docs/http/ngx_http_core_module.html#variables 
页 面 中 得 看 ， 这 里 不 再 重复 。 


在 15.1 节 的 例子 中 我 们 使 用 的 变量 $remote_addr 实 际 上 就 是 
ngx_http_core_module 模 块 定义 的 ， 它 通过 ngx_http_core_variables 数 组 有 





static ngx_http_variable t ngx_http_core variables[] = { 
{ ngx_string("remote addr"), NULL, 
ngx_http_variable_remote addr, 0, 0, 0 }, 

} 








ngx_http_variables_add_core_vars 方 法 会 将 ngx_http_core_variables 数 
组 里 的 所 有 核心 变量 添加 到 Nginx 框 架 中 。 下 一 节 我 们 再 谈 这 个 过 程 是 
怎样 进行 的 。 


2.2) 在 2.1 步 之 后 ， 其 他 HTTP 模 块 才 可 以 在 各 目的 preconfiguration 
方法 中 加 入 自 定义 的 内 部 变量 ，15.3 节 中 有 一 个 简单 的 例子 。 


3) 解析 配置 文件 http{} 块 中 的 配置 项 ， 根 据 配 置 项 名 称 找到 其 对 应 
模块 的 ngx_command_t 结 构 体 ， 根 据 解 析 方 法 来 处 理 配置 项 。 


3.1) 需要 使 用 变量 的 模块 ， 通 常会 在 解析 配置 的 这 一 步 中 将 竺 使 
用 的 变量 索引 化 。 为 什么 呢 ? 因为 变量 索引 化 是 有 代价 的 ， 所 有 索引 化 
的 变量 都 会 导致 存储 请 求 的 结构 体 ngx_http_request_t 增 加 内 存 占用 。 而 
索引 化 又 是 有 好 处 的 ， 它 的 算法 复杂 度 是 O(1)， 而 使 用 散 列 表 则 先 需 要 
hash 出 散 列 值 ， 再 需要 处 理 散 列 桶 冲突 后 的 链表 裔 历 问 题 。 那 么 ， 是 否 
索引 变量 就 与 server、location 配 置 相关 了 ， 上 所 以 只 有 确定 会 用 到 变量 的 
请 求 才 进行 索引 ， 这 样 通常 都 把 是 否 使 用 变量 交 给 配置 项 决定 。 











4) 调用 各 HTTP 模 块 的 postconfiguration 方 法 。 这 时 解析 完 配 置 了 ， 
初始 化 完 变 量 了 ， 这 里 会 决定 模块 怎样 介入 到 HTTP 请 求 的 处 理 中 。 





5) 调用 ngx_http_variables_init_vars 方 法 初始 化 HTTP 变量 。 这 人 一方 
法 主要 包括 3 个 子 步 又 。 





5.1) 一 个 变量 是 人 否 进 行 索引 ， 应 该 由 使 用 它 的 模块 决定 ， 而 不 是 
由 定义 它 的 模块 决定 。 这 样 束 可 能 带 来 冲突 ， 如 末 使 用 模块 案 引 了 一 个 
变量 ， 其 实 却 没有 其 他 模块 定义 它 上 怎么 办 ? 或 者 说 ， 有 模块 定义 了 它 ， 
但 是 这 个 模块 没有 编译 进 Nginx 怎 么 办 ? 所以， 





ngx_http_variables_init _vars 方 法 首先 要 确保 索引 了 的 变量 都 是 合法 的 : 
索引 过 的 变量 必须 是 定义 过 的 ; 其次， 使 用 索引 变量 的 模块 只 知道 索引 
某 个 变量 名 ， 此 时 需要 把 相应 的 变量 值 解析 方法 等 属性 也 设置 好 。 











5.2) 通常 变量 名 是 非常 明确 的 ， 可 以 在 C 代 码 中 定义 变量 时 用 hard 
code 的 方式 编写 变量 名 ， 然 而 还 有 一 些 变 量具 有 两 个 特点 : 它们 的 名 称 
是 未 知 的 ， 但 是 如 何 解 析 它 们 却 是 一 目 了 然 的 。 例 如 ，HTTP 的 URL 中 
的 变量 ， 就 像 请 求 /sitemap.xmlpage_num=2 里 的 page_num， 如 何 解 析 它 
是 非常 明确 的 ， 就 是 在 HITP 请 求 行 ? 符号 后 的 参数 中 按 规则 解析 出 
page_num 即 可 。 这 样 的 参数 五 花 八 门 ， 什 么 样 的 都 有 ， 解 析 方 法 实际 只 
有 一 个 : 根据 变量 名 在 一 段 字 符 串 中 找到 即 可 。 这 样 的 请 求 Nginx 总 结 
为 5 类 ， 它 们 仅 需 要 5 个 固定 的 解析 变量 方法 即 可 ， 而 每 类 中 的 变量 名 是 
不 确定 的 ， 由 使 用 变量 的 模块 决定 。 这 5 类 变量 都 由 HTTP 框 架 定 义 ， 而 
要 求 使 用 它们 的 模块 必须 在 变量 名 中 强制 定义 前 级 为 http_、 


sent_http_、upstream_http_、cookie 或 者 arg 。 这 5 类 变量 参见 表 15-1。 














表 15-1 5 类 特殊 HTTP 变 量 


变量 前 绿 解析 方法 
arg_ 请 求 的 URL 参数 ngx http_variable argument 
http_ 请 求 中 的 HTTP 头 部 ngx http_variable unknown header ln 
sent_ http_ 发 送 啊 应 中 的 HTTP 头 部 ngx http_variable unknown header out 


cookie Cookie 头 部 中 的 某 个 项 ngx http_variable_ cookie 





upstream http_ 后 端 服务 需 HITP 啊 应 头 部 ngx http_ upstream header _ variable 





5.3) 定义 变量 的 模块 是 希望 变量 可 以 被 快速 访问 的 ， 然 而 ， 它 不 











能 寄 希 望 于 变量 被 索引 ， 因 为 是 否 索引 是 使 用 变量 模块 的 权力 ! 于 是 定 
义 的 变量 就 需要 被 hash 为 散 列 表 来 加 速 访 问 。 另 一 个 问题 是 5.2 步 的 5 类 
名 字 不 明确 的 HTTP 变量 怎么 办 ? 只 有 使 用 变量 的 模块 才 知 道明 确 的 变 
量 名 ， 定 义 它们 的 ngx_http_core_module 模 块 不 知道 变量 名 就 无 法 按照 
变量 名 hash 成 散 列表 。 所 以 这 一 步 构 造 散 列表 ， 将 除 表 15-1 的 5 类 变量 以 
外 的 、 没 有 显 式 设置 不 要 hash (参见 15.2.2 节 〉 的 变量 生成 到 一 个 静态 
的 开 散 列表 中 。 











下 面 在 了 解 变量 的 工作 机 制 之 前 ， 还 要 先 介绍 相关 的 结构 体 。 





15.2.2 ”相关 数据 结构 详 述 








变量 由 变量 名 和 变量 值 组 成 。 对 于 同一 个 变量 名 ， 随 着 场景 的 不 同 
会 具有 多 个 不 同 的 值 ， 如 果 认 为 变量 值 和 变量 名 一 一 对 应 从 而 使 用 一 个 
结构 体 表 示 ， 毫 无 疑问 会 有 大 量 内 存 浪费 在 相同 的 变量 名 的 存储 上 。 因 
此 ，Nginx 中 有 一 个 保存 变量 名 的 结构 体 ， 叫 做 ngx_http_variable t， 它 
负责 指定 一 个 变量 名 字符 串 ， 以 及 如 何 去 解 析出 相应 的 变量 值 。 所 有 的 
变量 名 定义 ngx_http_variable_t 都 会 保存 在 全 局 唯一 的 
ngx_http_core_main_conf_t 对 象 中 ， 解 析 变 量 时 也 是 围绕 着 它 进行 。 














存储 变量 值 的 结构 体 叫 做 ngx_http_variable_value_t。 它 既 有 可 能 是 
在 读 取 变量 值 时 被 创建 出 来 ， 也 有 可 能 是 在 初始 化 一 个 HTTP 请 求 时 就 





预 创建 在 ngx_http_request_t 对 象 中 ， 这 将 视 描 述 变 量 名 的 
ngx_http_variable_t 结 构 体 成 员 而 定 。 





1. 变 量 的 定义 ngx_http_variable_t 


我 们 先 来 看 看 ngx_http_variable_t 的 结构 : 





struct ngx_http_variable s { 
// name 就 是 字符 串 变 量 名 ， 例 如 


nginx.conf 中 常见 的 


$remote_addr 这 样 的 字符 串 ， 


ngx_str_t name; 
// 如 果 需 要 变量 最 初 赋值 时 就 进行 变量 值 的 设置 ， 那 么 可 以 实现 


set_handler 方 法 。 如 果 我 们 定义 的 


// 内 部 变量 允许 在 


nginx.conf 中 以 


Set 方 式 又 重新 设置 其 值 ， 那 么 可 以 实现 该 方法 (参考 





args 参 数 ， 


// 它 就 是 一 个 内 部 变量 ， 同 时 也 允许 


Set 方 式 在 


nginx.conf 里 重新 设置 其 值 ) ， 详 见 


15 .4 节 


ngx_http_set_variable_pt set_handler,; 
// 每 次 获取 一 个 变量 的 值 时 ， 会 先 调用 


get_handler 方 法 ， 所 以 


Nginx 的 官方 模块 变量 的 解析 大 都 
// 在 此 方法 中 完成 


ngx_http_get_variable_pt get_handler; 
// 这 个 整数 是 作为 参数 传递 给 


get_handler、 


set_handler 回 调 方 法 使 用 


uintptr_t data; 
// 变量 的 特性 ， 下 文 详 述 


ngx_uint_t flags; 
// 这 个 数字 也 就 是 变量 值 在 请 求 中 的 缓存 数组 中 的 索引 


ngx_uint_t index; 


}; 
typedef struct ngx_http_variable s ngx_http_variable t; 








下 面 看 看 上 面 的 get_handler 和 set_handler 对 应 的 方法 类 型 
ngx_http_set_variable_pt 是 怎样 的 ， 当 本 章 后 续 定 义 新 的 自 有 变量 时 ， 整 
必须 要 实现 相应 的 解析 变量 值 的 方法 : 





typedef void (*ngx_http_set_ variable pt) (ngx_http_request _t *r, 


ngx_http_variable value t *v, uintptr_t data); 
typedef ngx_int_t (*ngx_http_get variable pt) (ngx_http_request t *r,ngx_http_variat 





可 以 看 到 ， 它 们 均 接收 3 个 参数 ， 表 示 请 求 的 [， 表 示 变 量 值 的 v， 
以 及 一 个 可 能 使 用 到 的 参数 data， 这 个 data 也 就 是 定义 变量 名 的 
ngx_http_variable_t 结 构 体 中 的 data 成 员 。 这 两 个 解析 方法 和 data 成 员 在 
15.2.5 市 会 详细 说 明 。 








flags 成 员 是 一 个 整 型 ， 它 是 按 位 来 设计 的 ， 目 前 仪 有 前 4 位 设 定 了 


含义 ， 所 以 共有 4 种 取 值 的 组 合 ， 这 前 4 位 定义 如 下 所 示 : 





#define NGX_HTTP_VAR_ CHANGEABLE 1 
#define NGX_HTTP_VAR_ NOCACHEABLE 2 
#define NGX_HTTP_VAR_INDEXED 4 
#define NGX_HTTP_VAR_NOHASH 8 





每 个 flags 标 志 位 的 含义 见 表 15-2。 


表 15-2 HTTP 变量 名 ngx_http_vatiable ft 中 的 flags 标 志 位 意义 


flags 标志 位 


让 
/< 


表示 对 应 的 变量 值 可 以 改变 ， 也 就 是 对 一 个 请 求 内 的 同一 个 变量 可 以 
反复 地 修改 其 变量 值 。 反 过 来 说 ， 如 果 没 有 这 个 标志 位 ， 一旦 对 一 个 赋 
过 值 的 变量 重新 赋值 就 会 报错 。 对 于 内 部 变量 ， 再 深入 看 看 可 以 知道 ， 
没有 这 个 标志 位 的 变量 ， 是 不 允许 一 次 以 上 定义 同一 变量 名 的 ， 因 为 多 
次 设置 变量 的 解析 方法 与 修改 变量 值 是 等 价 的 ， 我们 常 在 Nginx 启动 时 
发 现 错误 “the duplicate…variable”， 就 是 这 个 原因 。 特 别 对 于 15.4 节 
介绍 的 外 部 变量 ,它们 一 定 允 许 反复 修改 同一 变量 的 值 ， 所 以 必须 加 上 
该 标志 位 


NGX HTTP VAR CHANGEABLE 





flags 标志 位 


NGX HTTP VAR NOCACHEABLE 


NGX HTTP VAR INDEXED 


NGX HTTP VAR NOHASH 


不 要 缓存 这 个 变量 的 值 ， 每 次 使 用 变量 时 都 需要 重新 解析 。 为 什么 不 
呢 ? 因为 有 些 请 求 的 变量 会 在 执行 中 伴随 着 URL 跳 转 等 动作 


复 改变 > $uri 这 个 变量 ， 如 果 读 取 到 了 上 一 次 缓存 的 值 是 无 法 确定 


[证 

将 变量 索引 ， 加 速 访问 。 为 什么 又 要 缓存 一 些 变量 的 值 呢 ? 因为 有 些 
变量 在 一 次 请 求 的 执行 中 是 永远 不 变 的 ， 例 如 $request_uri 这 个 变量 ， 
它 表 示 最 初 接收 自 客户 端的 请 求 URI， 自 然 不 会 变化 ,那么 缓存 之 后 的 
反复 使 用 速度 就 会 更 快 

不 要 把 这 个 变量 hash 到 散 列 表 中 。 为 什么 会 想 着 使 一 个 变量 不 做 散 列 
优化 呢 ? 这 是 因为 散 列 表 也 是 需要 消耗 内 存 的 ， sh = 
个 可 选 变 量 提供 给 其 他 模块 使 用 ， 并 是 要 求 如 果 有 其 他 模块 使 用 该 变量 
就 必须 索引 化 再 使 用 ( 即 不 能 调用 ngx_http_get_variable 方法 来 获取 变 
量 值 )， 这 样 ， 这 个 变量 就 不 用 浪费 散 列 表 的 存储 空间 了 


© 提示 “Nginx 中 有 一 个 “Embedded Variables” 概 念 ， 例 如 


ngx_http_fastcgi_module、ngx_http_gzip_module 等 模块 都 提供 了 这 样 


的 “嵌入 式 变量 le 其 实 ， 


这 种 变量 就 是 指 本 模块 提供 了 可 选 变量 仅 供 


其 他 模块 (而 不 是 更 改 nginx.conf 配 置 文件 的 用 户 ) 使 用 ， 而 其 他 模块 使 
用 时 也 只 能 先 把 变量 索引 化 再 使 用 ， 不 能 依据 散 列 表 使 用 变量 。 这 
种 “内 入 式 变量 ”通常 就 会 指定 flags 中 含有 


NGX_HTTP_VAR_NOHASH 标 志 。 这 里 有 两 点 需要 注意 : 四 变量 是 可 


选 的 ， 也 就 是 说 ， 使 用 了 该 模块 的 其 他 Nginx 模 块 不 用 这 个 变量 一 样 可 
以 工作 ， 所 以 这 个 变量 不 应 当 占 用 散 列 表 ; 他 若 其 他 模块 使 用 该 变量 ， 
则 必须 先 通 过 nex_http_pget_vatiable _ index 方 法 把 变量 索引 化 ， 才 能 获取 


变量 值 。 


2. 变 量 值 ngx_http_variable_value_t 


描述 变量 值 的 结构 为 ngx_http_variable_value_t， 实 际 上 等 价 于 


ngx_variable_value t: 





typedef ngx_variable value t ngx_http_variable value t; 








看 看 它 包 括 哪些 成 员 : 





typedef struct { 
// 变量 值 必 须 是 在 一 段 连续 内 存 中 的 字符 串 ， 值 的 长 度 就 是 


en 成 员 


unsigned len:28; 
// valid 为 


1 时 表示 当前 这 个 变量 值 已 经 解析 过 ， 且 数据 是 可 用 的 


unsigned valid:1; 
// no_cacheable 为 


1 时 表示 变量 值 不 可 以 被 缓存 ， 它 与 


ngx_http_variable_t 结 构 体 


flags 成 员 


// 里 的 


NGX_HTTP_VAR_NOCACHEABLE 标 志 位 是 相关 的 ， 即 设置 这 个 标志 位 后 


no_cacheable 就 会 为 


unsigned no_cacheable:1; 
// not_found 为 


1 表示 当前 这 个 变量 值 已 经 解析 过 ， 但 没有 解析 到 相应 的 值 


unsigned not_found:1; 
// 仅 由 


ngx_http_10og_module 模 块 使 用 ， 用 于 日 志 格式 的 字符 转 义 ， 其 他 模块 通常 忽略 这 


上 
这 
识 


unsigned escape:1; 
// data 就 指向 变量 值 所 在 内 存 的 起 始 地 址 ， 与 


len 成 员 配 合 使 用 


u_char *data; 
} ngx_variable value t; 








3. 存 储 变 量 名 的 数据 结构 


HTTP 框 架 的 核心 结构 体 ngx_http_core_main_conf_t 中 有 3 个 成 员 与 
HTTP 变 量 是 相关 的 ， 如 下 所 示 : 





typedef struct { 
// 存储 变量 名 的 散 列 表 ， 调 用 


ngx_http_get_variab1le 方 法 获取 未 索引 的 变量 值 时 就 靠 这 个 


// 散 列 表 找 到 变量 的 解析 方法 


ngx_hash_t variables_hash,; 


// 存储 索引 过 的 变量 的 数组 ， 通 常 各 模块 使 用 变量 时 都 会 在 


Nginx 启 动 阶段 从 该 数组 中 获得 索引 号 ， 


Nginx 运 行 期 内 ， 如 果 变 量 值 没有 被 缓存 ， 就 会 通过 索引 号 在 


Variables 数 组 中 找到 


// 变量 的 定义 ， 再 解析 出 变量 值 


ngx_array_t variables,; 
// 用 于 构造 


Variables_hash 散 列表 的 初始 结构 体 


ngx_hash_keys_arrays_t *variables_keys,; 
} ngx_http_core _ main conf_t; 














这 3 个 成 员 中 ，variables_hash、variables 会 在 Nginx 的 正常 运行 中 使 
用 ， 而 variables_keys 纯 粹 只 在 Nginx 启 动 时 临时 用 一 下 ， 它 只 是 用 于 构 
建 variables_hash 散 列表 ，variables_hash 成 功 生成 后 variables_keys 就 功 成 
吴 退 了 。 


4. 绥 存 变 量 值 的 数据 结构 





变量 值 如 果 可 以 被 缓存 ， 那 么 它 一 定 只 能 组 存在 每 一 个 HITP 请 求 
内 ， 对 于 Nginx 这 样 一 个 Web 服务器 来 说 ， 不 可 能 为 不 同 的 HTTP 请 求 组 
存 同一 个 值 。 因 此 缓存 的 变量 值 就 在 表述 一 个 HTTP 请 求 的 
ngx_http_request_t 结 构 体 中 ， 如 下 : 








struct ngx_http_request _s { 
// variables 数 组 存储 所 有 序列 化 了 的 变量 值 ， 数 组 下 标 即 为 索引 号 


ngx_http_variable_value_t *variables,; 





当 HTTP 请 求 刚 到 达 Nginx 时 ， 就 会 创建 缓存 变量 值 的 variables 数 
组 ， 如 下 : 





ngx_http_request 七 * 
ngx_http_create_request(ngx_connection_t *c) 


ngx_http_request_t 让 

ngx_http_core main conf_t *cmcf,; 

cmcf = ngx_http_get_ module main conf(r, ngx_http_core module); 
// 缓存 变量 值 的 








Variab1les 数 组 下 标 ， 与 索引 化 的 、 表 示 变 量 名 的 数组 


cmcf->variables 下 标 ， 


// 它们 是 一 一 对 应 的 


r->variables = ngx_pcalloc(r->pool, cmcf->variables.nelts * sizeof(ngx_htt 





一 旦 某 个 变量 的 ngx_http_variable_value_t 值 结构 体 被 缓存 ， 取 值 时 
就 会 优先 使 用 它 。 


5. 内 存 布 局 





了 解 了 相应 的 结构 体 后 ， 我 们 可 以 从 它们 在 Nginx 内 存 中 如 何 布局 
入 手 ， 掌 握 其 用 法 。 


欲 了 解 其 内 存 布局 ， 当 然 首先 从 ngx_http_core_main_conf t 中 的 3 个 
成 员 来 串 起 各 结构 体 。variables_keys 仅 用 于 构造 variables_hash 散 列表 ， 


它 也 是 Nginx 构 造 散 列表 的 必 经 步 又， 读者 朋友 可 以 参考 第 7 章 ， 这 里 不 
再 介绍 。 我 们 重点 看 看 variables_hash 散 列表 中 的 变量 与 variables 索 引 数 
组 中 的 变量 有 何 关 联 ， 参 见 图 15-2。 


ngx_hash_elt_t 


len 
指 问 
EE PR PE EE 
开 散 列表 


ngx_http_core_main_conf t 


ngx_http_variable_t 
variables_hash 
variables_keys name 


flags (无 NGX_HTTP VAR_NOHASH ) 
| 





variables 


| 





flags 同 时 满足 二 者 的 同名 变量 ，flags 外 的 参数 必须 完全 一 致 


索引 0 ”索引 1 索引 2 索引 3 索引 4 
ks 
ngx http_variabis_ t 构 成 的 数组 
SS 


™ 
\ 


\ ngx_http_variable_t 


、 
| 


， flags ( 含 NGX_HTTP VAR_INDEXED ) 


图 15-2 ”定义 变量 的 nex_http_vatiable t 结 构 体 在 内 存 中 的 布局 





可 以 看 到 ， 散 列表 与 索引 数组 中 都 存放 着 各 目的 ngx_http_variablef 


结构 体 ， 即 使 name 相 同 的 同一 个 变量 ， 如 果 既 被 索引 又 被 hash 的 话 ， 仍 
然 会 有 两 份 ngx_http_variable_{t 结 构 体 ， 除 了 flags 成 员 会 有 不 同 外 ， 它 们 
的 其 他 成 员 都 是 相等 的 。 使 其 各 成 员 “ 相 等 "这 个 操作 是 在 图 15-1 的 第 5.1 
步骤 的 ngx_http_variables_init_vars 方 法 完成 的 ， 感 兴趣 的 朋友 可 以 陪读 
源 代码 。 





这 里 的 含义 就 是 ， 同 一 个 变量 名 称 可 以 同时 既 被 索引 又 被 hash， 但 
一 定 只 有 一 种 解析 变量 的 方法 ， 所 以 ， 同 一 变量 可 以 同时 拥有 两 个 
ngx_http_variable_t 结 构 体 。 








无 论 是 索引 还 是 hash， 都 必须 针对 明确 的 变量 名 。 可 是 在 表 15-1 中 
却 有 5 类 特殊 变量 ， 它 们 只 是 前 级 固定 为 http_、sent_http_、 
upstream_http_、cookie 或 者 arg_， 唯 有 在 模块 使 用 1 个 具体 的 变量 时 才 
能 确定 完整 的 变量 名 称 。 确 定 了 完整 名 称 的 特殊 变量 是 可 以 被 索引 的 ， 
却 不 应 该 被 hash 到 散 列 表 中 ， 为 什么 呢 ? 因为 进入 散 列表 的 变量 都 是 由 
模块 重 定义 解析 方法 的 ， 而 这 5 类 特殊 变量 则 可 以 复 用 HTTP 框 架 已 经 准 
备 好 的 通用 解析 方法 。 所 以 索引 变量 、 散 列表 变量 、 特 殊 变 量 会 组 合 为 
5 种 关系 ， 如 图 15-3 所 示 。 











variables_hash 存 放 的 hash 过 的 变量 


同时 被 we 
了 S| 的 变 a 量 


variables 存 放 的 索引 过 的 变量 


被 索引 的 特 丈 变量 





图 15-3 索引 变量 、hash 变 量 、 特 殊 变 量 间 的 集合 关系 





图 15-3 中 有 4 个 要 点 : 
1) 同一 个 变量 可 以 同时 被 hash 和 索引 。 


2) 变量 并 非 要 么 在 散 列 表 中 ， 要 么 在 索引 数组 中 。 对 于 特殊 变 
， 是 可 以 绕 开 二 者 用 ngx_http_get_variable 方 法 获取 其 值 的 。 


tn 


3) 对 于 特殊 变量 ， 是 可 以 使 用 索引 的 方式 来 获取 其 值 的 ， 这 也 是 
最 常用 的 方式 。 











4) 不 要 重 定 义 特 殊 变 量 ， 重 定义 的 特殊 变量 可 能 存在 于 散 列 表 中 
(未 设置 NGX_HTTP VAR_NOHASH 标 志 位 ) 。 





下 面 我 们 通过 图 15-4 来 看 看 索引 过 的 变量 在 内 存 中 是 怎么 使 用 的 。 





变量 的 索引 由 两 部 分 组 成 ， 一 是 定义 变量 的 ngx_http_variable_t 结 构 
体 构成 的 索引 数组 ;二 是 描述 变量 值 的 ngx_http_variable_value t 结 构 体 
构成 的 数组 。 前 者 在 Nginx 只 有 全 局 的 唯一 一 份 ， 存 储 在 
ngx_http_core_main_conf t 结 构 体 的 variables 中 ; 后 者 对 每 一 个 HTTP 请 
求 都 会 有 一 份 ， 存 储 在 ngx_http_request_t 结 构 体 的 variables 中 。 这 两 者 
间 同 属于 一 个 变量 的 名 字 、 值 在 各 自 数 组 中 的 索引 号 都 是 一 一 对 应 的 。 











想 以 索引 方式 使 用 变量 的 模块 ， 都 会 在 模块 初始 化 阶段 获得 索引 
号 ， 在 Nginx 运 行 中 、HTTP 请 求 到 达 时 ， 则 会 根据 这 个 索引 号 ， 要 么 从 
ngx_http_variable_t 构 成 的 数组 中 找到 变量 定义 并 使 用 get_handler 方 法 解 





析出 变量 值 (如 果 flags 参 数 指明 可 以 缓存 ， 那 么 还 会 缓存 到 请 求 中 ) ， 
要 么 从 ngx_http_variable_value_t 构 成 的 数组 中 直接 获得 缓存 的 变量 值 。 


这 个 数组 主要 用 于 存 
放 所 有 被 索引 过 的 变 
量 定义 ,特别 是 其 解 
析出 变量 值 的 方法 


ngx_http_core_main_conf t 


variables_hash 
| | 







索引 0 索引 1 索引 2 索引 3 索引 4 





* 
ngx_http_variable_t 构 成 的 数组 |/ 
/ 







使 用 变量 的 模块 
sss===d 
index 索 引号 ==4 


index==4 


get_handler 解 析 值 


ngx_http_variable_t 
[| 





设 转 值 ” 获 得 缓存 值 


ngx_http_request_t 
| 







索引 0 ; 索引 1 ; 索引 2 ; 索引 3 ; 索引 4 










ngx_http_request_t 





这 样 的 数组 


:ngx_http;_variablé_value_t: 用 于 缓存 变 
量 值 ， 每 个 







构成 的 变量 值 预 分 配 数组 
: : : : 请 求 都 有 该 
数组 





ngx_http_variable_value_ t+ 
see 
] 全 = 


en， 变 量 值 的 长 度 
data， 指 向 变量 值 





图 15-4 索引 过 的 变量 内 存 使 用 示意 图 





每 一 个 HITP 请 求 都 必须 为 所 有 缓存 的 变量 建立 
ngx_http_variable_value_t 数 组 ， 这 似乎 有 些 内 存 浪 颖 ， 因 此 ， 不 使 用 索 
引 而 是 散 列 表 来 使 用 变量 也 是 可 以 的 ， 此 时 其 内 存 布 局 如 图 15-5 所 示 。 
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iabl : 
人 : ; 未 索引 变量 则 构造 新 的 ngx_http_variable_value_t 


索引 0 ; 索引 1 ; 索引 2 ; 索引 3 ; 索引 4 















len， 变 量 值 的 长 度 
data， 指 回 变量 值 


















len， 变 量 值 的 长 度 
data， 指 回 变量 值 








图 15-5 散 列 过 的 变 


此 时 ， 使 用 变量 的 模块 不 用 在 Nginx 初 始 化 阶段 做 些 什么 ， 只 要 这 
个 变量 已 经 有 模块 定义 过 ， 那 么 在 处 理 请求 时 ， 仅 需要 把 变量 名 字符 串 
按照 hash 方 法 求 出 散 列 值 ， 就 可 以 在 ngx_http_core_main_conf t 结 构 体 的 
variables_hash 散 列表 中 找到 定义 变量 的 ngx_http_variable_t 结 构 体 ， 如 果 
其 flags 成 员 指 明 变 量 是 被 索引 的 ， 那 么 会 根据 index 成 员 直 接 向 请 求 的 
variables 数 组 里 获得 预 分 配 的 ngx_http_variable_value_t 结 构 体 ， 这 个 变 
量 值 奉 没有 解析 过 ， 束 会 用 该 结构 体 传 给 get_handler 方 法 解析 、 绥 存 
《如 果 可 以 的 话 ) 。 如 果 flags 成 员 没有 说 明 变 量 被 索引 过 ， 那 么 就 会 在 
请 求 的 内 存 池 里 新 分 配 1 个 ngx_http_variable_value_t 结 构 体 ， 用 于 传递 
给 get_handler 方 法 解析 、 承 载 变量 值 。 











15.2.3 ”定义 变量 的 方法 


定义 新 的 内 部 变量 时 ， 通 过 ngx_http_add_variable 方 法 进行 ， 其 定 
义 如 下 : 





ngx_http_variable t * 
ngx_http_add variable(ngx_conf_t *cf, ngx_str_t *name, ngx_uint_t flags); 





在 15.2.1 节 已 经 介绍 过 ， 添 加 变量 必须 是 在 preconfiguration 回 调 方法 
中 ， 第 1 个 参数 cf 直接 把 preconfiguration 中 的 ngx_conf_t 指 针 传 入 即 可 ， 
cf 的 用 途 有 两 个 : 定义 新 变量 一 定 会 放 到 全 局 唯一 的 
ngx_http_core_main_conf t 结 构 体 ， 参 数 cf 可 以 找到 这 个 全 局 配置 结构 


体 ， 分 配 变 量 相 关 结 构 体 的 内 存 时 ， 可 以 用 cf 的 内 存 池 。 第 2 个 参数 就 
是 变量 的 名 称 。 第 3 个 参数 等 价 于 ngx_http_variable_t 中 的 flags 成 员 。 





返回 值 就 是 已 经 准备 好 的 、 用 于 定义 变量 的 ngx_http_variable_t 结 构 
体 。 此 时 ， 这 个 结构 体 的 name 和 flags 成 员 已 经 设置 好 了 ， 这 时 需要 定义 
变量 模块 做 的 工作 就 是 指定 解析 方法 ， 包 括 指定 get_handler、 
set_handler (很 少 设置 ) 、data〈 如 果 有 必要 的 话 ) 。 在 15.2.5 节 中 再 来 
介绍 如 何 实现 解析 方法 。 





G 注 章 ”如果 这 个 变量 曾经 被 其 他 模块 添加 过 ， 那 么 此 时 的 返回 
值 ngx_http_variable_t 就 是 其 他 模块 已 经 设置 过 的 对 象 ， 它 的 get_handler 
等 成 员 可 能 已 经 设置 过 了 。 开 发 模块 新 变量 时 应 当 妥 善 处 理 这 种 变量 名 


冲突 问题 。 
15.2.4 ”使 用 变量 的 方法 


使 用 变量 时 会 使 用 表 15-3 中 所 列 的 4 个 方法 。 











使 用 变量 时 有 两 种 方式 : 第 一 种 方式 是 索引 变量 ， 表 15-3 的 前 3 个 
方法 都 只 用 于 索引 变量 ， 索 引 变 量 效率 更 高 〈 且 可 以 被 缓存 ) ， 但 可 能 
会 消耗 稍 多 点 的 内 存 ; 第 二 种 方式 是 非 索引 的 、hash 过 的 变量 ， 
ngx_http_get_variable 方 法 用 于 此 目的 。 

















@ 注意 “如果 这 个 变量 被 索引 过 ， 那 么 ngx_http_get_variable 方 法 
会 优先 在 nex_http_tequest t 中 缓存 变量 值 的 vatiables 数 组 中 的 获取 值 。 是 
否 被 索引 过 的 依据 就 是 检查 flags 参 数 是 否 含 有 
NGX_HTTP_VAR_INDEXED 标 志 位 。 


表 15-3 ”获取 HTITP 变 量 值 的 3 个 方法 


方法 名 意 义 
设置 变量 被 索引 ， 并 获得 索引 号 ， 它 是 使 用 ngx _ http_get indexed _ variable、 
ngx_http_get flushed_ variable 方法 的 前 置 方法 
调 / 日 它 意味 着 这 个 变量 会 被 频繁 地 使 用 ,希望 Nginx 处 理 这 个 变量 时 效率 更 
高 ， 体 现在 : 
ngx http_ get variable index e 变量 值 可 以 被 缓存 ， 更 复读 取 时 不 用 每 次 解析 
e 定义 变量 的 解析 方法 时 ， 可 以 通过 索引 直接 找到 该 方法 进行 解析 ， 而 不 是 
通过 操作 散 列 表 
e Neginx 初始 化 HITP 请 求 时 ， 就 需要 为 这 个 变量 预 分 配 ngx _http variable 
value tf 变量 值 结构 体 
根据 ngx_http_get_variable index 得 到 的 索引 号 ， 获 取 被 索引 过 的 变量 的 
值 。 若 变量 被 解析 过 一 次 后 其 值 是 会 被 缓存 的 ， 这 样 该 方法 再 次 调用 后 将 会 
直接 获取 缓存 过 的 值 ， 而 不 是 重新 解析 。 这 个 方法 是 忽略 NGX _HITP _VAR_ 
NOCACHEABLE 标志 位 的 
与 ngx_http_get indexed_variable 相似 ， 区 别 是 : 如 果 flags 中 设置 了 NGX 
HITP VAR NOCACHEABLE 标志 人 位， 那么 ngx_http_get indexed Variable 方 











ngx http get indexed variable 











ngx http get flushed variable 





法 会 忽略 这 个 标志 位 ， 本 方法 则 会 不 使 用 已 经 缓存 的 变量 值 ， 每 次 取 值 时 皆 重 
新 解析 
根据 变量 名 称 ， 从 被 hash 过 的 散 列 表 里 找 到 相应 的 变量 并 调用 其 解析 方法 
ngx http_ get variable 获得 值 ， 这 里 不 存在 缓存 变量 值 的 可 能 。 同 时 车 变量 是 属于 表 15-1 时 的 $ 种 


特殊 变量 ， 也 可 以 从 本 方法 中 获取 解析 出 的 值 


15.2.5 ”如何 解析 变量 


首先 回顾 一 下 解析 变量 的 主要 方法 get_handler 的 方法 原型 : 





typedef ngx_int_t (*ngx_http_get variable pt) (ngx_http_request _t *r,ngx_http_variat 





参数 r 和 data 都 用 来 帮助 生成 变量 值 ， 而 v 则 是 存放 值 的 载体 。 结 构 
体 v 已 经 分 配 好 内 存 了 调用 get_handler 的 函数 负责 ) ， 当 然 分 配 好 的 
内 存 中 是 不 包括 字符 串 变 量 值 的 。 可 以 使 用 请 求 ? 的 内 存 池 来 分 配 新 的 
内 存放 置 变 量 值 ， 这 样 请 求 结束 时 变量 值 就 会 被 释放 ， 可 见 变 量 值 的 生 
命 周期 与 请 求 是 一 致 的 ， 而 变量 名 则 不 然 。 将 参数 v 的 data 和 1len 成 员 指 
癌变 量 值 字符 串 即 完成 了 变量 的 解析 。 这 一 过 程 本 来 共性 特征 并 不 多 ， 
然而 uintptr_t data 参 数 却 有 一 些 通 用 的 “玩法 ”， 本 节 则 简要 介绍 一 下 : 




















(1) uintptr_t data 参 数 不 起 作用 


如 果 只 是 生成 一 些 和 用 户 请 求 无 关 的 变量 值 ， 例 如 当前 时 间 、 系 统 
负载 、 人 磁盘 状况 等 ， 那 么 这 与 读者 朋友 的 需求 有 关 ， 使 用 各 种 手法 获得 
变量 值 后 赋 给 参数 v 的 data 和 len 成 员 即 可 。 或 者 说 ，ngx_http_request_t*r 
中 的 成 员 已 经 足够 解析 出 变量 值 了 ，data 参 数 不 用 也 圈 。 举 个 例子 ， 
HTTP 框 架 提供 了 一 个 变量 一 一 body_bytes_sent， 表 示 一 个 请 求 的 响应 
包 体 长 度 ， 常 用 在 access.log 访 问 日 志 中 ， 它 的 解析 方法 设置 为 
ngx_http_variable_body_bytes_sent，uintptr_t data 因 为 不 使 用 则 设 为 0， 
如 下 所 示 : 











static ngx_http_variable t ngx_http_core variables[] = { 
{ngx_string("body_bytes_sent"),NULL, 
ngx_http_variable_body_bytes_sent, 

90, 0, 0}, 
} 





而 ngx_http_variable_body_bytes_sent 解 析 啊 应 包 体 长 度 变 量 的 值 时 


仅 从 请 求 r 中 就 获取 到 足够 信息 了 ， 如 下 : 





static ngx_int_t 
ngx_http_variable_body_bytes_sent(ngx_http_request _t *r, 
ngx_http_variable value t *v, uintptr_t data) 


off_t sent,; 
// 发 送 的 总 响应 值 减 去 响应 头 部 即 可 


sent = r->connection->sent - r->header_size; 





(2) uintptr_t data 参 数 作为 指针 使 用 


uintptr_t 是 一 个 可 以 放置 指针 的 整 型 ， 所 以 ，uintptr_t data 就 被 设计 
为 既 用 来 做 整 型 偏 移 值 ， 又 用 来 做 指针 。 下 面 看 看 HTTP 框 架 把 data 用 来 
做 指针 的 一 个 例子 ， 我 们 知道 有 5 类 特殊 变量 ， 它 们 以 特殊 的 字符 串 打 
头 ， 例 如 http_ 或 者 sent_http_， 实 际 上 每 一 个 这 样 的 变量 其 解析 方法 都 
大 同 小 异 ， 遍 历 解析 出 来 的 r->headers_in.headers 或 者 r- 
>headers_in.headers 数 组 ， 找 到 变量 名 再 返回 其 值 即 可 。 那 么 怎样 设计 通 
用 的 解析 方法 呢 ? 答案 就 是 把 uintptr_t data 作 为 指针 指向 实际 的 变量 名 
字符 串 。 如 下 所 示 ， 当 出 现 了 如 http_ 这 样 的 变量 被 模块 使 用 时 ， 就 把 
data 作 为 指针 来 保存 实际 的 变量 名 字符 串 
v[il.name Cngx_http_variables_init_vars 初 始 化 特殊 变量 时 的 代码 段 ) 。 














if (ngx_strncmp(v[il].name.data, "http_", 5) == 0) { 
v[il].get_handler = ngx_http_variable_unknown_header_in,; 
vlil].data = (uintptr_t) &v[i].name; 


} 








而 解析 变量 的 get_handler 方 法 再 把 data 转 为 ngx_str_t 字 符 串 变量 名 即 
可 ， 如 下 : 





static ngx_int_t 

ngx_http_variable_unknown_header_in(ngx_http_request_t *r, 
ngx_http_variable value t *v, uintptr_t data) 
return ngx_http_variable unknown_header(v, (ngx_str_t *) data, &r->headers_in.he 


} 








ngx_http_variable_unknown_header 方 法 就 只 是 授 历 ngx_list_t 链 表 类 
型 的 headers 数 组 ， 找 到 符合 变量 名 的 头 部 后 ， 将 其 值 作为 变量 值 返 回 即 
名 5 





(3) uintptr_t data 参 数 作为 序列 化 内 存 的 相对 偏 移 量 使 用 





很 多 时 候 ， 变 量 值 很 有 可 能 束 是 原始 的 HTTP 字 符 流 中 的 一 部 分 连 
续 字 符 串 ， 如 果 能 够 复 用 ， 就 不 用 为 变量 的 字符 串 值 再 次 分 配 、 找 贝 内 
存 了 。 男 外 各 HTTP 模 块 在 使 用 get_handler 解 析 变 量 时 ，HTTP 框 架 可 能 
在 请 求 的 目 动 解析 过 程 中 已 经 得 到 了 需要 的 变量 值 ， 这 部 分 计算 工作 也 
可 以 不 用 再 做 一 过 。 那 么 能 不 能 据 此 两 点 加 快 解析 速度 呢 ? data 参 数 作 
为 整 型 设计 的 目的 就 在 于 此 。 





HTTP 框 架 中 会 解析 很 多 请 求 的 头 部 ， 如 http_host、http_user_agent 
等 ， 它 们 实际 上 已 经 在 请 求 头 部 接收 完整 时 就 已 经 解析 完了 ， 如 果菜 个 
Nginx 模 块 需要 使 用 这 个 变量 ， 完 全 可 以 复 用 ， 能 够 复 用 的 依据 在 于 : 
HTTP 框 架 解析 后 的 变量 值 ， 其 定义 成 员 在 ngx_http_request_t 结 构 体 里 





的 位 置 是 固定 不 变 的 。 这 样 就 可 以 用 data 承 载 偏 移 量 直接 把 
ngx_http_variable_value t 里 的 data、len 指 向 变量 值 字符 串 即 可 。 例 如 主 
机 名 变量 http_host 其 实 正 对 应 着 ngx_http_request_t 结 构 体 里 的 headers_in 
成 员 的 host 成 员 ， 而 访问 浏览 器 http_user_agent 变 量 则 对 应 着 
ngx_http_request_t 结 构 体 里 的 user_agent 成 员 ， 它 们 的 解析 方法 都 是 专门 
用 于 找 出 已 经 解析 过 HTTP 头 部 的 变量 的 ngx_http_variable_header 方 法 ， 
而 data 则 是 偏 移 量 ， 如 下 : 











static ngx_http_variable t ngx_http_core variables[] = { 

{ ngx_string("http_host"), NULL, ngx_http_variable header, 
offsetof(ngx_http_request_t, headers_in.host), 0, 0 }, 

{ ngx_string("http_user_agent"), NULL, ngx_http_variable header, 
offsetof(ngx_http_request_t, headers in.user agent), 0, 0 }, 

} 





在 第 4 章 我 们 已 经 介绍 过 offsetof 方 法 ， 它 接收 两 个 参数 ， 并 认为 第 1 
个 参数 是 一 个 struct 绪 构 体 ， 第 2 个 参数 是 其 成 员 ， 返 回 的 就 是 成 员 在 其 


结构 体 中 的 偏 移 量 。 看 看 ngx_http_variable_header 方 法 做 了 些 什 么 : 








static ngx_int_ 

ngx_http_variabJe_header(ngx_http_request_t *r, ngx_http_variable value t *V， 
uintptr_t data) 

{ 


ngx_table elt t *h; 
// data 偏 移 量 就 是 解析 过 的 


ngx_table_elt_t 类 型 的 成 员 ， 在 


ngx_http_request_t 结 构 体 中 的 偏 移 量 


h = *(ngx_table elt t **) ((char *) r + data); 
if (h) { 
// 将 


en 和 


data 指 向 字符 串 值 


VvV->len = h->value.1len; 
VvV->valid = 1; 
VvV->no_cacheable = 0; 
V->not_found = 0; 
V->data = h->value.data,; 
} else { 
V->not_found = 1; 
} 


return NGX_OK; 


15.3 ”定义 内 部 变量 


15.2 市 已 经 完整 介绍 了 定义 内 部 变量 的 方法 ， 本 市 我 们 扩展 15.1 届 
的 例子 ， 定 义 新 的 内 部 变量 供 其 他 模块 使 用 《就 像 马 入 式 变 量 ， 即 本 模 
块 配 置 项 是 不 文 持 该 变量 的 ) ， 例 如 使 hgx_http_log_module 模 块 可 以 将 
新 定义 的 变量 记录 到 access.log 访 问 日 志文 件 中 。 





我 们 定义 的 这 个 新 的 租 入 式 内 部 变量 叫做 is_chrome， 顾 名 思 义 ， 束 
是 表示 这 个 请 求 是 否 来 自 于 chrome 浏 览 器 。 首 先 ， 要 在 源 代码 中 定义 这 


个 变量 名 称 ， 如 下 : 





static ngx_str_t new varaible_ is chome = ngx_string("is_chrome"); 





在 15.2.1 节 中 我 们 说 过 ， 必 须 在 preconfiguration 阶 段 定 义 变量 ， 所 以 
先 要 声明 一 个 在 preconfiguration 阶 段 执行 的 方法 : 





static ngx_int_t ngx_http_mytest_add_ variable(ngx_conf t *cf); 








并 在 ngx_http_module_t 中 新 增 调用 ngx_http_mytest_add_variable 方 
法 ?9 如 下 3 





static ngx_http_module t ngx_http_testvariable module ctx = 





ngx_http_mytest_add_ variable, /* preconfiguration */ 
ngx_http_mytest_init, /* postconfiguration */ 





}; 





下 面 我 们 开始 实现 添加 变量 的 ngx_http_mytest_add_variable 方 法 : 





ngx_http_mytest_add_variable 方 法 : 





static ngx_int_t 
ngx_http_mytest_add variable(ngx_conf_t *cf) 





ngx_http_variable t *V; 
// 添加 变量 


Vv = ngx_http_add variable(cf, &new varaibJe_is_chome，NGX_HTTP_VAR_CHANGEABLE ) ， 
if (v == NULL) { 
return NGX_ERROR,; 
} 
// 如 果 
Is_chrome 这 个 变量 没有 被 添加 过 ， 那 么 


get_handler 就 是 


NULL 空 指针 


v->get_handler = ngx_http_ischrome_variable; 
// 这 里 的 


data 成 员 没 有 使 用 价值 ， 故 设 为 


v->data = 0; 
return NGX_oK; 





最 后 定义 is_chrome 变 量 的 解析 方法 : 





static ngx_int 

ngx_http_ischrome_variable(ngx_http_request_t *r, ngx_http_variable value t *yv, 
uintptr_t data) 

{ 


/7 交际 主 


r->headers_in,chrome 已 经 根据 


USser_agent 头 部 解析 过 请 求 是 否 来 自 于 


Chrome 浏 览 器 


if (r->headers_in.chrome) { 
*vV = ngx_http_variable_ true_value; 
return NGX_OK; 


*v = ngx_http_variable _ null value; 
return NGX_OK， 





如 此 ，is_chrome 变 量 已 经 在 这 个 模块 中 添加 到 Nginx 中 了 ， 然 而 这 
个 测试 模块 却 没 有 相关 的 配置 项 直接 使 用 该 变量 。 所 以 只 有 其 他 使 用 到 
该 变量 的 模块 才 可 能 提供 相应 的 配置 项 在 nginx.conf 中 供 大 家 使 用 。 例 
如 ，access_log 里 可 以 这 么 配置 : 





log_format main '$remote addr - [$time_ local] "$request" ' 
'$status $body_bytes_sent "$http_referer" ' 
'"$http_user_agent" ischrome: $is_chrome” 

















这 样 就 会 记录 请 求 是 否 来 自 于 chrome。 其 实 这 个 变量 也 就 是 15.1 节 


介绍 过 的 嵌入 式 变 量 。 


15.4 外 部 变量 与 脚本 引擎 


ngx_http_rewrite_ module 模 块 使 用 了 Nginx 的 脚本 引擎 ， 提 供 了 外 部 
变量 的 功能 。 “外 部 变量 ?与 前 儿 贡 介绍 的 变量 有 什么 不 同 呢 ? 这 里 的 定 
义 是 ， 变 量 名 称 是 在 nginx.conf 的 配置 文件 里 声明 的 《不 像 在 C 源 代码 中 
定义 的 内 部 变量 ) ， 且 在 配置 文件 里 确定 了 变量 的 赋值 。 








ngx_http_rewrite_module 模 块 定义 的 外 部 变量 格式 为 : 





set $variable value; 








这 一 行 配置 通过 set 关 键 字 定义 了 一 个 在 nginx.conf 中 指定 的 新 变量 
variable， 并 将 其 赋值 为 value。 这 个 value 是 一 个 文本 字符 串 ， 实 际 上 
value 中 还 可 以 含有 多 个 变量 ， 也 可 以 是 变量 与 文本 字符 串 的 组 合 。 这 种 
外 部 变量 的 定义 非常 有 用 ， 尤 其 是 配合 rewrite 重 定向 URL、 半 关键 字 
等 ， 可 以 起 到 意 想 不 到 的 效果 ， 我 们 可 以 在 互联 网 上 找到 多 种 巧妙 的 用 
法 ， 通 过 修改 nginx.conf 就 得 到 了 丰富 的 功能 。 











很 多 程序 员 认为 nginx.conf 的 设计 有 些 脚本 语言 的 味道 ， 因 为 它 可 
以 定义 变量 、 可 以 跳 转 到 不 同 的 程序 段 执 行 、 拥 有 if 这 样 的 判断 型 配置 
等 (当然 这 些 都 是 ngx_http_rewrite_module 模 块 提供 的 ， 使 用 它们 必须 





要 将 ngx_http_rewrite_ module 模 块 编 译 进 Nginx) 。 但 这 门 “ 脚 本 语言 ” 却 





有 些 独 特 的 味道 ， 与 编译 型 语言 相 比 ， 它 是 不 存在 预 编 译 这 个 步骤 的 ， 

只 有 Nginx 局 动 过 程 中 才 会 把 脚本 式 配 置 项 载 入 Nginx 进 程 中 当然， 把 
Nginx 的 局 动 理解 为 “编译 ?步骤 的 话 ， 它 其 实 更 像 是 编译 语言 ) 。 与 解 

释 型 语言 相 比 ， 它 又 不 是 执行 到 某 一 行 脚本 时 才 会 解释 它 ， 而 是 Nginx 
一 启动 就 会 检查 配置 项 的 合法 性 ， 并 把 所 有 的 脚本 式 语句 都 “解释 ”为 C 
程序 ， 等 待 HTTP 请 求 到 来 时 执行 








外 部 变量 虽然 在 Nginx 局 动 时 束 补 编译 为 C 代 码 ， 但 它们 是 在 请 求 处 
理 过 程 中 才 被 执行 、 生 效 的 。 惑 像 下 面 这 段 配置 : 


Jocation /image/ { 
set imagewidth 100; 


Jocation / { 





在 这 段 配置 里 ， 只 有 请 求 匹 配 到 /image/ 后 ， 外 部 变量 imagewidth 才 
会 被 定义 并 被 赋值 为 100 (或 者 imagewidth 已 经 被 定义 过 而 被 修改 值 为 
100) ， 这 样 之 后 的 脚本 、 模 块 才 可 以 使 用 imagewidth 变 量 。 反 之 ， 请 
求 没 有 匹配 到 /image/ 就 不 会 执行 这 段 set 脚 本 。 


因此 ， 外 部 变量 的 设计 可 以 总 结 为 两 个 步 又: 








1) Nginx 启 动 时 将 配置 文件 中 的 set 脚 本 式 配置 编译 为 相关 的 数据 与 
执行 方法 。 


2) 接收 到 HTTP 请 求 时 ， 在 


NGX_HTTP SERVER_REWRITE _ PHASE 或 者 
NGX_HTTP_REWRITE_PHASE 阶 段 中 查找 匹配 了 的 location 下 是 否 有 竺 
执行 的 脚本 ， 如 果 有 则 依次 执行 。 


本 节 并 不 会 完整 介绍 ngx_http_rewrite_module 模 块 用 到 的 所 有 脚本 
语法 ， 以 及 Nginx 脚 本 引擎 的 完整 用 法 。 然 而 外 部 变量 已 经 足够 有 代表 
性 了 ， 通 过 上 面 的 配置 作为 例子 介绍 其 工作 原理 ， 读 者 朋友 就 可 以 清晰 
地 了 解 到 脚本 引擎 的 用 法 ， 进 而 可 以 展开 阅读 ngx_http_rewrite_ module 
模块 源 代码 了 解 更 多 的 细 市 。 








15.4.1 相关 数据 结构 


同一 段 脚 本 被 编译 进 Nginx 中 ， 在 不 同 的 请 求 里 执行 时 效果 是 完 
不 同 的 ， 所 以 ， 每 一 个 请 求 都 必须 有 其 独 有 的 脚本 执行 上 下 文 ， 或 者 称 
为 脚本 引擎 ， 这 是 最 关键 的 数据 结构 。 在 Nginx 中 ， 是 由 
ngx_http_script.h 文 件 里 定义 的 ngx_http_script_engine_t 结 构 体 充当 这 一 
角色 ， 如 下 所 示 : 





typedef struct { 
// 指向 待 执行 的 脚本 指令 


u_char *ip; 
// 变量 值 构成 的 栈 


ngx_http_variable value t *sp; 
// 脚本 引擎 执行 状态 


ngx_int_ status; 
// 和 向 当 亲 条 未 蛋 兴 所属 网 


HTTP 请 求 


ngx_http_request_t *request; 


} ngx_http_script_engine_t; 











我 们 来 看 看 与 外 部 变量 相关 的 4 个 成 员 。 


ngx_http_variable_value_t*sp 是 一 个 栈 。 我 们 知道 任何 语言 都 需 
要 “ 栈 ” 这 样 一 个 数据 结构 作为 编译 工具 ， 例 如 在 函数 的 调用 、 表 达 式 的 
解析 时 。 对 set 定 义 的 外 部 变量 也 一 样 ， 它 需要 sp 这 个 栈 来 存放 变量 值 。 
栈 当然 也 有 大 小 ， 目 前 的 默认 大 小 为 10 个 变量 值 。 


request 很 简单 ， 指 向 了 HTTP 请 求 。 


u_charx*ip 可 以 想象 为 寄存器， 因为 它们 的 目的 是 一 致 的 ， 都 是 指 
问 下 一 行将 要 执行 的 代码 。 然 而 p 却 是 一 个 u_char* 类 型 ， 它 指向 的 类 型 
古 不 确定 的 。 它 指向 的 一 定 是 待 执 行 的 脚本 指令 ， 难 道 没 有 规律 吗 ? 用 
面 问 对 象 的 语言 来 说 ， 它 指 癌 的 是 实现 了 ngx_http_script_code_pt 接 口 的 
类 。 妆 然 C 语 言 里 没有 接口 、 类 的 概念 ， 在 C 语 言 里 要 想 实 现 上 述 目 
的 ， 通 常会 用 崔 套 结构 体 的 方法 ， 比 如 表示 接口 的 结构 体 A， 要 放 在 表 
示 实 现 接口 的 关 一 一 结构 体 B 的 第 1 个 位 置 。 这 样 一 个 指 癌 B 的 指针 ， 也 
可 以 强制 转换 类 型 为 A 再 调用 A 的 成 员 。 如 果 读 者 朋友 觉得 比较 抽象 ， 























那么 u_char*ip 指 向 ngx_http_script_code_pt 函 数 指针 就 是 一 个 非常 好 的 例 
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首先 ，ngx_http_script_code_pt 是 一 个 函数 指针 ， 当 然 它 即 使 是 一 个 
结构 体 也 无 所 谓 。 看 看 它 的 定义 : 





typedef void (*ngx_http_script_code_pt) (ngx_http_script_ engine t *e); 











ngx_http_script_code_pt 的 唯一 参数 就 是 脚本 引擎 
ngx_http_script_engine_t， 它 表示 了 当前 指令 的 脚本 上 下 文 。 


ngx_http_script_code_pt 相 当 于 抽象 基 类 的 一 个 接口 ， 所 以 会 有 相应 
的 结构 体 担当 类 的 角色 。 对 于 “set" 配 置 来 说 ， 编 译 变量 名 〈 即 第 1 个 参 
数 ) 由 一 个 实现 了 ngx_http_script_code_pt 接 口 的 类 担当 ， 这 个 类 实际 上 
是 由 结构 体 ngx_http_script_var_code_t 来 承担 的 ， 如 下 所 示 : 





typedef struct { 
// 在 本 节 的 例子 中 ， 


code 指 向 的 脚本 指令 方法 为 





ngx_http_script_set_var_code 
ngx_http_script_code_pt code; 
// 表示 





ngx_http_request_t 中 被 索引 、 缓 存 的 变量 值 数 组 


variables 中 ， 当 前 解析 的 、 


// Set 设置 的 外 部 变量 所 在 的 索引 号 


uintptr_t index; 
} ngx_http_script_var_code t,; 








我 们 可 以 注意 到 ， 第 1 个 成 员 就 是 ngx_http_script_code_pt code， 这 
意味 着 可 以 把 ngx_http_script_var_code_t 强 转 为 ngx_http_script_code_pt 方 
法 执行 。 


看 到 了 uintptr_t 类 型 的 index 成 员 ， 大 家 可 能 又 会 想 ， 又 要 “多 用 
途 * 了 吗 ? 既 作 普 通 整 型 又 做 指针 ?这 里 纯粹 只 是 Nginx 的 习惯 而 已 ， 
index 成 员 只 用 来 做 表示 索引 号 的 整 型 ， 用 于 与 ngx_http_request_t 请 求 中 
索引 化 的 variables 变 量 值 配合 工作 。 这 里 我 们 已 经 看 到 ，set 定 义 的 外 部 
变量 只 能 作为 索引 变量 使 用 《〈 不 能 作为 hash 变 量 使 用 ) 。 








set 的 第 2 个 参数 是 变量 值 ， 它 也 需要 一 个 新 的 结构 体 


ngx_http_script_value_code_t 来 编译 ， 看 看 它 的 定义 : 





typedef struct { 
// 在 本 节 的 例子 中 ， 


code 指 向 的 脚本 指令 方法 为 


ngx_http_script_value_code 
ngx_http_script_code_pt code; 
// 若 外 部 变量 值 是 整数 ， 则 转 为 整 型 号 赋 给 








Value， 否 则 


Value 为 


0 
uintptr_t value; 
// 外 部 变量 值 ( 


Set 的 第 


2 个 参数 ) 的 长 度 


uintptr_t text_len,; 
// 外 部 变量 值 的 起 始 地 址 


uintptr_t text_data; 
} ngx_http_script_value code t; 








对 于 ngx_http_script_code_pt 方 法 的 实现 我 们 在 15.4.3 节 再 解释 。 那 
么 为 什么 一 行 set 脚 本 要 分 别 由 编译 变量 名 、 编 译 变量 值 的 2 个 结构 体 来 
表示 了 呢 ? 因为 set 有 很 多 不 同 的 使 用 场景 ， 对 变量 名 来 说 ， 就 存在 变量 名 
首次 出 现 与 非 首次 出 现 ， 而 变量 值 就 有 纯 字 符 串 、 字 符 串 与 其 他 变量 的 
组 合 等 情况 。 把 变量 名 的 编译 提取 为 ngx_http_script_var_code_t 结 构 
体 ， 使 所 有 变量 名 的 编译 可 以 复 用 其 index 成 员 ， 而 具体 的 
ngx_http_script_code_pt 指 令 执行 则 可 以 各 自 实现 ， 把 变量 值 的 编译 提取 
为 ngx_http_script_value_code_t 结 构 体 则 可 以 复 用 text_len、text_data 成 
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ngx_http_script_engine_t 是 随 着 HTTP 请 求 到 来 时 才 创 建 的 ， 所 以 它 
无 法 保存 Nginx 启 动 时 就 编译 出 的 脚本 。 保 存 编译 后 的 脚本 这 个 工作 实 
际 上 是 由 ngx_http_rewrite_loc_conf t 结 构 体 承担 的 ， 如 下 所 示 : 





typedef struct { 
// 保存 着 所 属 


location 下 的 所 有 编译 后 的 脚本 (按照 顺序 ) 


ngx_array_t *codes,; 
// 每 一 个 请 求 的 


ngx_http_script_engine _t 脚 本 引擎 中 都 会 有 一 个 变量 值 栈 ， 





// 即 上 面 提 到 的 


ngx_http_variable_value _t *Ssp， 它 的 大 小 就 是 


stack_size 
ngx_uint_t stack_size; 
} ngx_http_rewrite_ loc_ conf_t; 





从 名 称 就 可 以 看 出 ，ngx_http_rewrite_loc_conf t 其 实 就 是 
ngx_http_rewrite_module 模 块 在 location 级 别 的 配置 结构 体 ， 即 每 一 个 
location 下 都 会 有 1 个 ngx_http_rewrite_loc_conf t 结 构 体 。 如 果 这 个 
location 下 没有 脚本 式 配 置 ， 那 么 其 成 员 codes 数 组 就 是 空 的， 否则 codes 
数组 就 会 放置 承载 着 被 解析 后 的 脚本 指令 的 结构 体 。 


成 员 codes 数 组 的 设计 是 比较 独特 的 。 前 文 我 们 说 过 ， 脚 本 指令 都 
是 实现 了 “接口 ngx_http_script_code_pt” 的 各 个 不 同 的 充当 “类 ”的 结构 
体 ， 这 些 结构 体 可 以 是 ngx_http_script_var_code_t、 
ngx_http_script_value_code t 等 ， 它 们 的 类 型 不 同 ， 占 用 的 内 存 也 不 同 ， 
如 何 把 它们 整个 放 入 1 个 数组 中 呢 (注意 : 不 是 把 它们 的 指针 放 到 数组 
中 ! ) ? 以 下 3 点 就 可 以 做 到 : 


1) codes 数 组 设计 成 每 个 元 素 仅 占 1 个 字 市 的 大 小 ， 也 惑 是 说 ， 我 





们 不 奢望 一 个 数组 元 素 就 能 存放 表示 1 个 脚本 指令 的 结构 体 。 


2) 每 次 要 将 1 个 指令 放 入 codes 数 组 中 时 ， 将 根据 指令 结构 体 的 占 
用 内 存 字 节 数 N， 在 codes 数 组 中 分 配 N 个 元 素 存 储 这 1 个 指令 ， 再 依次 
把 指令 结构 体 的 内 容 部 拷贝 到 这 N 个 数组 成 员 中 。 如 下 所 示 : 











void * 
ngx_http_script_start_ code(ngx_ pool t *pool, ngx_array _t **codes, size _t size) 





if (*codes == NULL) { 
// codes 数 组 的 每 


1 个 元 素 只 占 


工 个 季节 


*codes = ngx_array_create(pool, 256, 1); 
If (*codes == NULL) { 
return NULL; 


// 这 个 


Size 就 是 类 似 





ngx_http_script_value_code_t 表 示 脚 本 指令 的 结构 体 所 占用 的 内 存 字 节 数 ， 


// 这 个 


ngx_array_push_n 就 会 直接 创建 


Size 个 数组 元 素 ， 仅 用 来 存储 


1 个 表示 指令 的 结构 体 


return ngx_array_push_n(*codes, size); 





3) HTTP 请 求 到 来 、 脚 本 指令 执行 时 ， 每 执行 完 一 个 脚本 指令 的 
ngx_http_script_code_pt 方 法 后 ， 该 方法 必须 主动 地 告知 所 属 指 令 结构 体 
占用 的 内 存 数 N， 这 样 从 当前 指令 所 在 的 codes 数 组 索引 中 加 上 N 后 惑 是 


T= 





这 样 我 们 就 把 实现 外 部 变量 的 关键 结构 体 都 介绍 了 ， 再 以 图 15-6 来 
形象 地 表示 内 存 中 它们 之 间 的 关系 。 





图 15-6 以 “set$variable value;” 配 置 项 作为 示例 ， 两 个 HTTP 请 求 (A 
和 B) 同时 执行 到 该 行 脚 本 ， 其 中 ，A 请 求 正 准备 执行 值 value 的 指令 
ngx_http_script_value_code_t， 而 B 请 求 已 经 执行 完 值 的 入 栈 ， 正 要 执行 
指令 ngx_http_script_var_code_ t。ngx_http_script_engine_t 脚 本 引擎 的 sp 
成 员 始 终 指向 变量 值 栈 里 正 要 操作 的 值 ， 而 认 成 员 则 始终 指向 将 要 执行 
的 下 一 条 指令 结构 体 。 





15.4.2 ”编译 “set”* 脚 本 


仍然 以 set 为 例 看 看 脚本 配置 是 如 何在 Nginx 的 启动 过 程 中 编译 的 。 
当 发 现 “set$variable value:” 配 置 时 ， 其 编译 流程 (处 理 set 配 置 的 
ngx_http_rewrite_set 方 法 ) 如 图 15-7 所 示 。 


详细 介绍 一 下 图 15-7 的 各 个 步 又: 


1) 首先 验证 set 后 续 参 数 的 合法 性 ， 例 如 第 1 个 参数 必须 是 以 $ 符 号 
开始 的 变量 名 。 


2) 在 15.2.3 节 我 们 介绍 过 定义 内 部 变量 的 ngx_http_add_variable 方 
法 ， 添 加 外 部 变量 一 样 是 调用 这 个 方法 。 需 要 注意 的 是 ， 外 部 变量 是 允 
许 重复 定义 的 ， 即 可 以 先 执行 sSet$variable value1 再 执行 set$variable 
value2， 这 样 当 后 者 调用 ngx_http_add_variable 方 法 时 ， 返 回 的 
ngx_http_script_var_code_t 结 构 体 其 实 是 前 者 已 经 定义 好 的 。 所 以 对 于 
外 部 变量 而 言 ，ngx_http_add_variable 方 法 传 入 的 flags 必 须 含 
NGX_HTTP_VAR_CHANGEABLE 标 志 位 (参见 表 15-2)〉。 
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图 15-6 ”外 部 变量 实现 的 各 数据 结构 间 的 内 存 关系 示意 图 


图 中 以 “set$variable value;” 作 为 示例 ， 脚 本 由 右 向 左 解 析 为 


negx_http_script_value_code_t、 ngx_http_script_ var_ code tf 





1 ) 验证 set 第 1 个 参数 必须 是 $ 开 头 的 变量 





2 ) 调用 ngx_http_add_variable 方 法 添加 这 个 外 部 变量 


3 ) 调用 ngx_http_get_variable_index 方 法 将 变量 索引 化 处 理 


4 ) 若 变 量 定义 的 get_handler 未 设置 过 ， 晶 不 为 5 类 特殊 变量 ， 重 设 get_handler 防 止 出 错 








5 ) 设置 第 2 个 值 参 数 的 脚本 处 理 方 法 


5.1 ) 检查 参数 中 是 否 还 有 $ 打 头 的 变量 


[变量 值 中 不 再 含有 变量 ] 





[变量 值 含有 其 他 变量 ] 


5.2 ) 设置 处 理 字符 串 值 的 指令 ngx_http_script_value_code_t 


5.3 ) 设置 ngx_http_script_complex_value_code_t 处 理 含有 变量 的 值 








6 ) 检查 该 变量 是 否定 义 过 的 内 部 变量 、 且 set_handler 方 法 设置 过 


[变量 被 定义 过 、set_handler 也 设置 过 ] 


“2 


[set_handler 为 NULL 空 指针 ] 


7) 设置 变量 名 脚本 语句 的 处 理 方法 ngx_http_script_var_code t 


8 ) 设置 处 理 该 变量 的 方法 为 ngx_http_script_var_handler_code_t 





图 15-7 ”编译 set 脚 本 配置 的 流程 


3) 前 文 我 们 说 过 ， 变 量 是 分 为 定义 和 使 用 两 部 分 的 ， 唯 有 打算 使 
用 它 时 才 应 该 索引 化 ， 把 它 的 值 缓存 到 请 求 的 variables 数 组 中 。 而 对 
ngx_http_rewrite_ module 模 块 的 外 部 变量 而 言 ，set 配 置 既 定义 了 一 个 变 
量 ， 也 表明 会 使 用 这 个 变量 。 所 以 一 定 会 调用 
ngx_http_get_variable_index 方 法 把 变量 索引 化 的 ， 同 时 索引 值 会 保存 到 
ngx_http_script_var_code_t 结 构 体 的 index 成 员 里 (参见 15.4.1 市 )。 








4) 内 部 变量 的 get_handler 方 法 是 必须 实现 的 ， 因 为 通常 都 是 采 
ee a 
这 个 值 。 然 而 外 部 变量 是 不 同 的 ， 每 一 次 set 都 会 立刻 给 变量 重新 赋值 ， 
同时 读 取 变 量 值 时 ， 因 为 变量 值 是 被 索引 化 的 ， 所 以 可 以 直接 从 请 求 的 
variables 数 组 里 取 到 set 后 的 值 。 这 样 get_handler 似 乎 是 没有 用 武之 地 
的 。 然 而 ， 可 能 有 些 模 块 会 在 set 脚 本 执行 之 前 就 使 用 到 外 部 变量 了 ， 此 
时 外 部 变量 的 值 是 不 存在 的 ， 即 缓存 的 variables 数 组 里 变量 值 是 空 的 。 
从 15.2 节 可 知 ， 此 时 会 调用 get_handler 方 法 来 读 取 变 量 值 ， 所 以 外 部 变 
量 的 get_handler 方 法 也 不 可 以 为 NULL， 它 被 定义 为 ngx_http_rewrite_var 
方法 ， 这 个 方法 所 做 的 唯一 工作 就 是 把 变量 值 置 为 


ngx_http_variable_null_value 空 值 : 
































ngx_http_variable value t ngx_http_variable null value = 
ngx_http_variable(""); 








当 第 2 步 添加 变量 时 获得 的 ngx_http_variable_t 中 get_handler 为 NULL 
时 ， 如 果 变 量 名 的 前 级 属于 5 类 特殊 变量 (参见 表 15-1) ， 那 么 在 所 有 
配置 项 解析 完毕 后 (当然 也 包括 脚本 式 配 置 set〉 ， 在 图 15-1 的 第 5.2 步 又 
中 就 会 给 这 类 变量 重新 设置 get_handler 方 法 。 所 以 对 于 非 5 类 特殊 变量 
月 get_handler 为 NULL 时 ， 就 得 把 get_handler 设 置 为 ngx_http_rewrite_var 
方法 ， 使 得 外 部 变量 未 赋值 时 读 取 它 可 以 获得 空 值 。 














5) 开始 处 理 set 的 第 2 个 值 参 数 〈 即 调用 ngx_http_rewrite_value 方 法 
处 理 ) 。 





5.1) 这 个 参数 可 以 是 纯 字 符 串 ， 也 可 以 含有 其 他 变量 ， 这 二 者 之 
间 的 处 理 方 式 是 不 同 的 。 所 以 首先 检查 这 第 2 个 值 参数 里 有 没有 $ 符 号 ， 
藻 像 本 节 的 例子 set$variable value 中 值 中 是 没有 变量 的 ， 则 跳 到 5.2 执 


行 ， 否 则 执行 5.3 步 又 。 

















5.2) 到 这 里 我 们 已 经 可 以 开始 编译 纯 字 符 串 的 变量 值 了 。 就 像 上 
一 节 介绍 的 那样 ， 纯 字符 串 值 的 指令 结构 体 是 
ngx_http_script_value_code t， 我 们 首先 会 把 它 添加 到 所 在 location 下 的 
ngx_http_rewrite_loc_conf t 配 置 结构 体 的 codes 数 组 中 ， 如 下 : 





ngx_http_script_value code t *val; 
val = ngx_http_script_start_ code(cf->pool, &lcf->codes, 
sizeof(ngx_http_script_value code t)); 














接着 ， 如 同 15.4.1 节 介绍 过 的 那样 ， 将 ngx_http_script_value_code_t 


的 4 个 成 员 赋 值 : 





n = ngx_atoi(value->data, value->len); 
if (n == NGX_ERROR) { 
n = 0; 


val->code = ngx_http_script_value_code,; 
val->value = (uintptr_t) n; 

val->text_len = (uintptr_t) value->len,; 
val->text_data = (uintptr_t) value->data; 








实际 执行 脚本 指令 的 ngx_http_script_value_code 方 法 在 下 一 节 介 


绍 。 


5.3) 如 果 值 参数 中 含有 其 他 变量 ， 那 么 处 理 方式 会 复杂 一 些 。 此 
时 ngx_http_script_complex_value_code_t 会 作为 指令 结构 体 添 加 到 codes 
数组 中 。 本 章 不 对 此 做 详细 介绍 。 











6) 把 变量 值 编译 好 后 ， 再 来 编译 变量 名 。 如 果 set 的 变量 其 实 是 一 
个 定义 过 的 内 部 变量 ， 那 么 第 2 步 返 回 的 就 是 被 茶 个 Nginx 模 块 定义 过 的 
ngx_http_variable_t， 它 的 set_handler 很 可 能 设置 过 。 如 果 set_handler 设 


置 过 则 执行 第 8 步 ， 否 则 执行 第 7 步 。 








7) 大 部 分 情况 下 ， 内 部 变量 不 会 与 外 部 变量 混合 在 一 起 使 用 。 此 
时 ， 我 们 首先 把 ngx_http_script_var_code_t 指 令 结 构 体 添加 到 codes 数 组 
中 ， 再 把 变量 的 索引 号 传 到 index 成 员 ， 并 设置 变量 指定 的 执行 方法 为 


ngx_http_script_set_var_code〈 下 一 节 再 介绍 其 实现 ) ， 如 下 所 示 : 








vcode->code = ngx_http_script_set_var_code; 





vcode->index = (uintptr_t) index; 





8) 如 果 一 个 内 部 变量 希望 在 nginx.conf 文 件 中 用 set 命 令 修 改 其 值 ， 
那么 它 束 会 实现 set_handler 方 法 ， 意 思 是 ， 执 行 到 set 指 令 时 ， 解 析 变 量 
值 时 请 调用 这 个 set_handler 方 法 吧 。 如 何 实现 这 一 意图 呢 ?” 新 增 一 个 
ngx_http_script_var_handler_code_t 指 令 结构 体 ， 专 门 处 理 这 种 “内 外 泥 


用 "的 变量 : 





typedef struct { 





ngx_http_script_code_pt code; 
ngx_http_set_variable_ pt handler; 
uintptr_t data; 


} ngx_http_script_var_handler_code t; 








可 以 看 到 它 并 没有 index 成 员 ， 为 什么 昵 ?” 因 为 set_handler 方 法 是 由 
内 部 变量 定义 过 的 ， 这 个 方法 肯定 能 够 找到 变量 值 (不 需要 关心 它 是 否 
通过 索引 下 标 ) 。 





当 执 行 到 set 脚 本 指令 设置 这 个 变量 的 值 时 ， 就 调用 set_handler 方 法 
( 即 上 面 的 handler 回 调 方法 ) 处 理 。 


这 一 步骤 就 是 将 ngx_http_script_var_handler_code_t 指 令 结 构 体 添加 


到 codes 数 组 中 ， 并 正确 给 其 各 成 员 赋 值 : 





ngx_http_script_var_handler_code t *vhcode; 

vhcode = ngx_http_script_start_code(cf->pool, &lcf->codes, 
sizeof (ngx_http_script_var_handler_code t)); 

vhcode->code = ngx_http_script_var_set_handler_code; 

vhcode->handler = v->set_handler; 

vhcode->data = v->data,; 


ee | 

















它 的 data 成 员 就 被 赋值 为 set 第 2 个 参数 变量 值 ，handler 方 法 则 为 内 
部 变量 已 经 定义 过 的 set_ handler 方 法 ， 而 code 执 行 指令 方法 则 为 


ngx_http_script_var_set_handler_code， 下 一 节 我 们 会 详细 介绍 。 


15.4.3 ”脚本 执行 流程 


当 HTTP 请 求 执行 到 NGX_HTTP_SERVER_REWRITE_PHASE 或 者 
NGX_HTTP_REWRITE_PHASE 阶 段 时 ， 就 有 可 能 执行 脚本 《前 提 是 加 
入 了 ngx_http_rewrite_ module 模 块 ， 且 nginx.conf 里 有 该 模块 提供 的 脚本 
式 配 置 ) 。 图 15-8 展 示 了 执行 脚本 的 ngx_http_rewrite_handler 方 法 主要 


1 ) 获取 请 求 所 属 location 下 的 配置 ngx_http_rewrite_loc_conf t 
[location 下 是 否 存在 待 执行 脚本 ? ] 















2 为 于 T 





青 求 构建 脚本 引擎 ngx_http_script_engine tt 


3 ) 构建 脚本 引擎 的 数据 栈 sp 


4) 找 出 脚本 引擎 的 待 执行 指令 ip 
[检查 脚本 语句 是 否 执行 完毕 










[未 执行 完毕 ] 


5 ) 执行 脚本 对 应 的 ngx_http_script_code_pt 方 法 


图 15-8 ”执行 脚本 的 流程 


下 面 将 会 介绍 图 15-8 的 各 步 又， 同时 也 将 介绍 图 15-7 中 第 5.2、7、8 
步 中 编译 后 的 指令 


1) 首先 获取 location 所 属 的 ngx_http_rewrite_loc_conf t 结 构 体 ， 
为 所 有 的 脚本 指令 都 保存 在 它 的 codes 数 组 中 ， 所 以 检查 codes 数 组 是 否 
为 NULL 就 可 以 知道 ， 当 前 location 下 是 否 有 脚本 配置 存在 。 若 没有 脚 
本 ， 则 ngx_http_rewrite_module 方 法 可 以 直接 结 





2) 执行 脚本 前 ， 一 定 要 先 建立 一 个 脚本 引擎 
ngx_http_script_engine_t， 这 个 结构 体 只 为 这 个 请 求 、 这 个 location 服 
务 。 如 下 : 





ngx_http_script_engine_t *e; 
e = ngx_pcalloc(r->pool, sizeof(ngx_http_script_engine_t)); 














3) 建立 变量 值 构 成 的 栈 ， 如 下 所 示 : 





ngx_http_rewrite loc conf_t  *rlcf， 
rlicf = ngx_http_get_ module loc conf(r, ngx_http_rewrite module); 
e->sp = ngx_pcalloc(r->pool, 

rlcf->stack_size * sizeof(ngx_http_variable_ value_t)); 








4) 所 有 的 脚本 指令 都 在 rlcf->codes 数 组 中 ， 虽 然 每 个 指令 结构 体 大 
小 不 一 致 ， 但 有 两 点 可 以 确定 : 数组 的 第 1 个 成 员 就 是 第 1 个 指令 结构 
体 ; 每 个 指令 结构 体 的 第 1 个 成 员 一 定 是 ngx_http_script_code_pt 溺 数 指 
针 ， 所 以 可 以 先 把 ip 指 向 数组 首 地 址 ， 并 把 jp 强制 转化 为 


ngx_http_script_code_pt 方 法 执行 脚本 ， 其 中 每 一 个 方法 负责 把 ip 移 同 下 
一 条 待 执行 的 脚本 指令 ， 如 下 : 





// codes 数 组 第 
1 个 元 素 就 是 第 


1 个 指令 结构 体 


e->ip = rlcf->codes->elts,; 
// ip 指 向 


NULL 时 就 说 明 脚本 执行 完毕 


while (*(uintptr_t *) e->ip) { 
// 每 


1 个 指令 结构 体 的 第 
1 个 成 员 一 定 是 


ngx_http_script_code_pt 方 法 





code = *(ngx_http_script_code pt *) e->ip; 
// 执行 指令 方法 时 ， 该 方法 负责 移动 





ip 指 针 


code(e); 





5) 现在 我 们 可 以 详细 看 看 每 条 脚本 指令 执行 时 到 底 是 如 何 工 作 
的 。 图 15-7 中 第 5.2 步 里 编译 了 一 条 执行 纯 字 符 串 值 的 脚本 指令 结构 体 ， 
它 在 上 面 的 code(e) 执 行 时 方法 为 ngx_http_script_value_code， 看 看 到 底 





做 丁 坚 什么; 





void 
ngx_http_script_value code(ngx_http_script_engine t *e) 








ngx_http_script_value code t *code,; 
// 由 于 





ngx_http_script_code_pt 是 指令 结构 体 的 第 





1 个 成 员 ， 所 以 


ip 同 时 也 指向 了 指令 结构 体 。 


// 对 于 编译 纯 字符 事变 量 值 而 言 ， 其 指令 结构 体 为 


ngx_http_script_value_code 七 ， 这 样 ， 





// 就 从 
codes 数 组 中 取 到 了 指令 结构 体 


code 
code = (ngx_http_script value code t *) e->ip; 
// 为 了 能 够 执行 下 一 条 脚本 指令 ， 先 把 





ip 移 到 下 一 个 指令 结构 体 的 地 址 上 。 移 动 方式 很 简单 ， 


// 右 移 


sizeof(ngx_http_script_value_code tl) 字 节 即 可 





e->ip += sizeof(ngx_http_script_value code t); 
// e->Sp 指 向 了 栈 顶 元 素 ， 处 理 脚 本 变量 值 时 ， 先 把 这 个 值 赋 给 栈 顶 元 素 





e->sp->len = code->text_len,; 
e->sp->data = (u_char *) code->text_data; 
// 栈 自动 上 移 


e->sp++; 





当 变 量 是 普通 的 外 部 变量 时 ， 图 15-7 中 第 7 步 设置 了 变量 名 的 指令 
执行 方法 为 ngx_http_script_set_var_code， 看 看 它 是 如 何 与 变量 值 栈 配 合 


的 ; 





void 


ngx 


ngx 


http_script_set_ var_code(ngx_http_script_engine t *e) 








ngx_http_request_t 党 让 
ngx_http_script_var_code t  *code 
// 同样 由 指向 





http_script_set_var_code 方 法 的 指针 





ip 可 以 获取 到 


ngx_ 


http_script_ 
// Var_code tt 指令 结构 体 





code = (ngx_http_script var_code t *) e->ip; 
// 将 


ip 移 到 下 一 个 待 执行 脚本 指令 


ngx 


ngx 


e->ip += sizeof(ngx_http_script_var_code t); 
r = e->request, 
// 首先 把 栈 下 移 ， 指 向 





http_script_Vvalue_code 设 置 的 那个 纯 字 符 串 的 变量 值 





e->sp--; 
// 根据 


http_script_var_code_t 的 





index 成 员 ， 可 以 获得 被 索引 的 变量 值 


// r->variables[code->index], 以 下 


5 行 语句 就 是 用 


e->Sp 栈 里 的 字符 串 来 设置 这 个 变量 值 


r->variables[code->index].len = e->sp->len; 
r->variables[code->index].valid = 1; 
r->variables[code->index].no_cacheable = 09; 
r->variables[code->index].not_found = 0; 
r->variables[code->index].data = e->sp->data,; 





如 果 set 的 变量 是 像 args 这 样 的 内 部 变量 ， 它 的 处 理 方 法 又 有 不 同 。 
因为 args 变 量 的 set_handler 方 法 不 为 NULL， 看 看 它 的 定义 : 





static ngx_http_variable t ngx_http_core variables[] = { 
{ ngx_string("args"), 
// set_handler 方 法 不 是 





NULL 
ngx_http_variable_request_set, 
ngx_http_variable_request, 
offsetof(ngx_http_request _t, args), 
// 允许 


Set 脚 本 来 重新 设置 这 个 





argSs 变 量 ， 所 以 必须 使 
flags 标 志 位 具有 


NGX_HTTP_VAR_CHANGEABLE 
NGX_HTTP_VAR_CHANGEABLE |NGX_HTTP_VAR_NOCACHEABLE, 0 }, 





在 图 15-7 的 第 8 步 中 ， 对 于 设置 了 set_handler 的 变量 ， 它 的 脚本 指令 


执行 方法 为 ngx_http_script_var_set_handler_code， 看 看 它 的 实现 : 





void 
ngx_http_script_var_set_handler_code(ngx_http_script_engine t *e) 








ngx_http_script_var_handler_ code t *code; 
// 同样 获取 到 指令 结构 体 





code = (ngx_http_script_ var_handler code t *) e->ip; 
// 移动 





ip 到 下 一 条 待 执行 指令 


e->ip += sizeof(ngx_http_script_var_handler_code t); 
// 变量 值 栈 移动 





e->Sp--:; 
// 将 请 求 、 变 量 值 传 递 给 


set_handler 方 法 执行 它 


code->handler(e->request, e->sp, code->data); 





所 有 的 脚本 指令 执行 时 都 与 上 面 3 个 例子 相似 ， 读 者 朋友 可 以 通过 
阅读 源 代 码 掌握 ngx_http_rewrite_module 模 块 的 更 多 脚本 实现 原理 。 


15 5 放生 


本 章 由 浅 入 深 地 先 从 如 何 使 用 内 部 变量 说 起 ， 进 而 分 析 了 内 部 变量 
的 工作 原理 ， 包 括 定 义 、 使 用 时 各 部 分 是 如 何 配合 使 用 的 ， 再 以 一 个 例 
子 资 明 如 何 定义 新 的 内 部 变量 《未 使 用 的 嵌入 式 变量 ) 。 


外 部 变量 是 由 ngx_http_rewrite_module 模 块 引入 的 ， 本 章 后 半 部 分 
说 明了 该 模块 的 脚本 引擎 是 如 何 实现 外 部 变量 的 ， 包 括 脚 本 在 Nginx 局 
动 时 的 编译 与 HTTP 请 求 到 来 时 的 执行 ， 并 分 析 了 内 部 变量 如 何 与 外 部 
变量 混合 着 使 用 。 








读者 朋友 通过 阅读 本 章 ， 可 以 在 开发 HITP 模 块 时 很 轻松 地 使 用 
HTTP 变 量 ， 甚 至 可 以 通过 对 比 ngx_http_rewrite_module 模 块 的 实现 ， 在 
自己 的 模块 中 开发 新 的 脚本 引擎 。 





第 16 章 slab 共享 内 存 








许多 场景 下 ， 不 同 的 Nginx 请 求 间 必 须 交 互 后 才能 执行 下 去 ， 例 如 
限制 一 个 客户 端 能 够 并 发 访问 的 请 求 数 。 可 是 Nginx 被 设计 为 一 个 多 进 
程 的 程序 ， 服 务 更 健壮 的 男 一 面 就 是 ，Nginx 请 求 可 能 是 分 布 在 不 同 的 
进程 上 的 ， 当 进程 间 需 要 互相 配合 才能 完成 请 求 的 处 理 时 ， 进 程 间 通 信 
开发 困难 的 特点 就 会 凸显 出 来 。 第 14 章 介绍 过 一 些 进 程 间 的 交互 方法 ， 
例如 14.2 节 的 共 至 内 存 。 然 而 如 果 进 程 间 需要 交互 各 种 不 同 大 小 的 对 
象 ， 需 要 共 译 一 些 复 条 的 数据 结构 ， 如 链表 、 树 、 图 等 ， 那 么 这 些 内 容 
将 很 难 支 撑 这 样 复杂 的 语义 。Nginx 在 14.2 节 共享 内 存 的 基础 上 ， 实 现 
了 一 套 高 效 的 slab 内 存 管 理 机 制 ， 可 以 帮助 我 们 快速 实现 多 种 对 象 间 的 
跨 Nginx worker 进 程 通 信 。 本 章 除 了 次 明 如 何 使 用 它 以 外 ， 同 时 还 会 详 
细 介 绍 实现 原理 ， 从 中 我 们 可 以 发 现 它 的 设计 初衷 及 不 适用 的 场景 。 
Slab 实现 的 源 代码 非常 高 效 ， 然 而 却 也 有 些 生 涩 ， 本 章 会 较 多 地 通过 源 
代码 说 明 各 种 二 进 制 位 操作 ， 以 帮助 读者 朋友 学 习 slab 的 编码 艺术 。 




















16.1 操作 slab 共 享 内 存 的 方法 





操作 slab 内 存 池 的 方法 只 有 下 面 5 个 : 





// 初始 化 新 创建 的 共享 内 存 


void ngx_slab_init(ngx_slab pool t *pool); 
// 加 锁 保护 的 内 存 分 配方 法 


void *ngx_slab _ alloc(ngx_slab pool t *pool, size t size); 
// 不 加 锁 保 护 的 内 存 分 配方 法 


void *ngx_slab alloc locked(ngx_slab pool t *pool, size t size); 
// 加 锁 保护 的 内 存 释 放 方 法 


void ngx_slab_ free(ngx_slab pool t *pool, void *p); 
// 不 加 锁 保护 的 内 存 释放 方法 


void ngx_slab_ free locked(ngx_slab pool t *pool, void *p); 








这 5 个 方法 是 src/core/mgx_slab.h 里 仅 有 的 5 个 方法 ， 其 精简 程度 可 见 
一 斑 。ngx_slab_init 由 Nginx 框 架 自 动 调用 ， 使 用 slab 内 存 池 时 不 需要 关 
注 它 。 通 常 要 用 到 slab 的 都 是 要 跨 进 程 通 信 的 场景 ， 所 以 
ngx_slab_alloc_locked 和 ngx_slab_free_locked 这 对 不 加 锁 的 分 配 、 释 放 内 
存 方法 较 少 使 用 ， 除 非 模块 中 已 经 有 其 他 的 同步 锁 可 以 复 用 。 因 此 ， 模 
块 开 发 时 分 配 内 存 调用 ngx_slab_alloc， 参 数 size 就 是 需要 分 配 的 内 存 大 
小 ， 返 回 值 就 是 内 存 块 的 首 地 址 ， 共 享 内 存 用 尽 时 这 个 方法 会 返回 














NULL; 释放 这 块 内 存 时 调用 ngx_slab_free， 参 数 p 就 是 ngx_slab_alloc 返 
回 的 内 存 地 址 。 还 有 一 个 参数 ngx_slab_pool t*pool 又 是 怎么 来 的 呢 ? 


很 简单 ， 由 下 面 的 ngx_shared_memory_add 方 法 即 可 拿 到 必须 的 


ngx_slab_pool_t*pool 参 数 : 





Nginx 初 始 化 


1 块 大 小 为 


Size、 名 称 为 


name 的 


Slab 共 享 内 存 池 


ngx_shm _ zone t *ngx_shared_memory_ add(ngx_conf t *cf, ngx_str_t *name, size t size, 








ngx_shared_memory_add 需 要 4 个 参数 ， 从 第 1 个 参数 ngx_conf_t*cf 
的 配置 文件 结构 体 就 可 以 推测 出 ， 该 方法 必须 在 解析 配置 文件 这 一 步 中 
执行 。 所 以 在 ngx_command_t 里 定义 的 配置 项 解析 方法 中 可 以 拿 到 
ngx_conf_t*cf， 通 常 ， 我 们 都 会 在 配置 文件 里 设置 共享 内 存 的 大 小 。 当 
然 ， 各 http 模 块 都 是 在 解析 http{} 配 置 项 时 才 会 被 初始 化 ， 定 义 http 模 块 
时 ngx_http_module t 的 8 个 回调 方法 里 也 可 以 拿 到 ngx_conf ts*cf。 








参数 ngx_str_t*name 是 这 块 slab 共 享 内 存 池 的 名 字 。 显 而 易 见 ， 


Nginx 进 程 中 可 能 会 有 许多 个 slab 内 存 池 ， 而 且 ， 有 可 能 多 处 代码 使 用 同 
一 块 slab 内 存 池 ， 这 样 才 有 必要 用 唯一 的 名 字 来 标识 每 一 个 slab 内 存 
池 。 


参数 size_t Size 设置 了 共享 内 存 的 大 小 。 


参数 void*xtag 则 用 于 防止 两 个 不 相关 的 Nginx 模 块 所 定义 的 内 存 池 恰 
好 有 具 有 同样 的 名 字 ， 从 而 造成 数据 错乱 。 所 以 ， 通 常 可 以 把 tag 参 数 传 
入 本 模块 结构 体 的 地 址 。tag 参 数 会 存放 在 ngx_shm_zone _t 的 tag 成 员 
中 。 


@ ;is 当 我 们 执行 -s teload 命 令 时 ，Nginx 会 重新 加 载 配置 文 
件 ， 此 时 ， 会 触发 再 次 初始 化 slab 共 享 内 存 池 。 而 在 该 过 程 中 ，tag 地 址 
同样 将 用 于 区 分 先后 两 次 的 初始 化 是 否 对 应 于 同一 块 共享 内 存 。 所 以 ， 
tag 中 应 传 入 全 局 变量 的 地 址 ， 以 使 两 次 设置 tag 时 传 入 的 是 相同 地 址 。 


如 果 前 后 两 次 设置 的 tag 地 址 不 同 ， 则 会 导致 即使 共享 内 存 大 小 没有 
变化 ， 旧 的 共享 内 存 也 会 被 释放 挤 ， 然 后 再 重新 分 配 一 块 同样 大 小 的 共 


享 内 存 ， 这 是 没有 必要 的 。 





ngx_shared_memory add 的 返回 值 就 是 用 来 拿 到 
ngX_slab_pool_ tspool 的 ， 如 果 返 回 NULL 表 示 获 取 共 享 内 存 失败 。 如 果 
参数 name 已 经 存在 ，ngx_shared_memory_add 会 比较 前 一 次 name 对 应 的 
共享 内 存 size 是 侣 与 本 次 size 参 数 相等 ， 以 及 tag 地 址 是 否 相 等 ， 如 采 相 














等 ， 直 接 返回 上 一 次 的 共享 内 存 对 应 的 ngx_shm_zone t， 人 否则 会 返回 
NULL。ngx_shm_zone_t 完 竟 是 怎样 帮助 我 们 拿 到 ngx_slab_pool_t*pool 
的 呢 ? 


先 来 看 看 ngx_shared_memory _ add 返回 了 一 个 怎样 的 结构 体 : 





typedef struct ngx_shm zone_s ngx_shm zone _t; 
struct ngx_shm zone_s { 
// 在 真正 创建 好 





Slab 共 享 内 存 池 后 ， 就 会 回调 


init 指 向 的 方法 


ngx_shm_zone_init_pt init; 
// 当 





ngx_shm_zone_init_pt 方 法 回调 时 ， 通 常 在 使 用 





Slab 内 存 池 的 代码 前 需要 做 一 些 初始 化 工作 ， 


// 这 一 工作 可 能 需要 用 到 在 解析 配置 文件 时 就 获取 到 的 一 些 参数 ， 而 


data 主 要 担当 传递 参数 的 职责 


void *data; 
// 描述 共享 内 存 的 结构 体 


ngx_shm_t shm; 
// 对 应 于 





ngx_shared_memory_add 的 


tag 参 数 


void *tag; 





拿 到 了 ngx_shm_zone_t 结 构 体 后 ，init 成 员 是 必须 要 设置 的 ， 因 为 
Nginx 后 续 创建 好 slab 内 存 池 后 ， 一 定 会 调用 init 指 问 的 方法 ， 这 是 约定 
好 的 。ngx_shm_zone_init_pt 函 数 指针 定义 如 下 : 





typedef ngx_int t (*ngx_shm_zone_init_pt) (ngx_shm_zone_t *zone, void *data); 








我 们 需要 实现 一 个 这 样 的 方法 ， 然 后 赋 给 ngx_shm_zone_t 的 init 函 数 
指针 。 这 个 方法 被 回调 时 ， 其 第 1 个 参数 就 是 ngx_shared_memory_add 返 
回 的 ， 而 且 是 刚刚 设置 过 其 init 函 数 指针 成 员 的 ngx_shm_zone t 结 构 体 。 
对 于 ngx_shm_zone_init_pt 的 第 2 个 参数 void*data， 在 理解 它 之 前 先 要 搞 
清楚 Nginx 的 reload 重 载 配 置 文件 流程 。 重 新 解析 配置 文件 意味 着 所 有 的 
模块 〈 包 括 http 模 块 ) 都 会 重新 初始 化 ， 然 而 ， 之 前 正 处 于 使 用 中 的 共 
享 内 存 可 能 是 有 数据 的 、 可 以 复 用 的 ， 如 果 丢 弃 了 这 些 旧 数据 而 重新 开 
辟 新 的 共享 内 存 ， 是 会 造成 严重 错误 的 。 所 以 如 果 处 于 重读 配置 文件 流 
程 中 ， 会 尽 可 能 地 使 用 旧 共 享 内 存 (如果 存在 的 话 ) ， 表 现在 
ngx_shm_zone_init_pt 的 第 2 个 参数 void*data 上 时 ， 就 意味 着 : 如 果 Nginx 
是 首次 启动 ，data 则 为 空 指针 NULL; 若是 重读 配置 文件 ， 由 于 配置 
项 、http 模 块 的 初始 化 导致 共享 内 存 再 次 创建 ， 那 么 data 就 会 指向 第 一 
次 创建 共享 内 存 时 ，ngx_shared_memory_add 返 回 的 ngx_shm_zone_t 中 
的 data 成 员 。 读 者 朋友 在 处 理 data 参 数 时 请 务必 考虑 以 上 场景 ， 考 虑 如 

















何 使 用 老 的 共 至 内 存 ， 以 避免 不 必要 的 错误 。 


16.2 ”使 用 Slab 共享 内 存 池 的 例子 








假定 这 样 一 个 场景 : 对 于 来 自 于 同一 个 IP 的 请 求 ， 如 果 客 户 端 访问 
某 一 个 URL 并 且 获 得 成 功 ， 则 认为 这 次 访问 是 重量 级 的 ， 但 需要 限制 过 
于 频率 的 访问 。 因 此 ， 设 计 一 个 http 过 滤 模 块 ， 若 访问 来 自 同一 个 IP 且 
URL 相 同 ， 则 每 N 秒 钟 最 多 只 能 成 功 访问 一 次 。 例 如 ， 设 定 10 秒 钟 内 仪 
能 成 功 访问 1 次 ， 那 么 某 浏览 器 0 秒 时 访问 /method/access 成 功 ， 在 第 1 秒 
在 仍然 收 到 来 自 这 个 卫 的 相同 请 求 ， 将 会 返回 403 拒 绝 访问 。 直 到 第 11 


秒 ， 这 个 IP 访 问 /method/access 才 会 再 次 成 功 。 


现在 来 实现 这 样 的 模块 。 首 先 ， 产 品级 的 Nginx 一 定 会 有 多 个 
worker 进 程 ， 来 自 同一 个 IP 的 多 次 TCP 连 接 有 可 能 会 进入 不 同 的 worker 
进程 处 理 ， 所 以 需要 用 共享 内 存 来 存放 用 户 的 访问 记录 。 为 了 高 效 地 碍 
找 、 插 入 、 删 除 访问 记录 ， 可 以 选择 用 Nginx 的 红 黑 树 来 存放 它们 ， 其 
中 关键 字 就 是 IP+URL 的 字符 串 ， 而 值 则 记录 了 上 次 成 功 访问 的 时 间 。 
这 样 请 求 到 来 时 ， 以 IP+URL 组 成 的 字符 串 为 天 键 字 查询 红 黑 树 ， 没 有 
查 到 或 查 到 后 发 现 上 次 访问 的 时 间距 现在 大 于 某 个 阀 值 ， 则 允许 访问 ， 
同时 将 该 键 值 对 插 下 红 黑 树 ; 反之 ， 若 查 到 了 且 上 次 访问 的 时 间距 现在 
小 于 某 个 阀 值 ， 则 拒绝 访问 。 











考虑 到 共享 内 存 的 大 小 有 限 ， 长 期 运行 时 如 果 不 考虑 回收 不 活跃 的 


记录 ， 那 么 一 方面 红 黑 树 会 越发 巳 大 从 而 影响 效率 ， 男 一 方面 共享 内 存 
会 很 快 用 尽 ， 导 致 分 配 不 出 新 的 结 点 。 所 以 ， 所 有 的 结 点 将 通过 一 个 链 
表 连 接 起 来 ， 其 插入 顺序 按 IP+URL 最 后 一 次 访问 的 时 间 组 织 。 这 样 可 
以 从 链表 的 首部 插入 新 访问 的 记录 ， 从 链表 尾部 取出 最 后 一 行 记录 ， 从 
而 检查 是 否 需 要 淘汰 出 共享 内 存 。 由 于 最 后 一 行 记录 一 定 是 最 老 的 记 

录 ， 如 果 它 不 需要 淘汰 ， 也 惑 不 需要 继续 遍历 链表 了 ， 因 此 可 以 提高 执 

















下 面 按照 以 上 设计 实现 一 个 http 过 小 模块 ， 以 此 作为 例子 说 明 slab 共 
享 内 存 池 的 用 法 。 





16.2.1 共享 内 存 中 的 数据 结构 








对 于 每 一 条 访问 记录 ， 需 要 包含 3 条 数据 : IP+URL 的 变 长 字符 串 
CURL 长 度 变化 范围 很 大 ， 不 能 按照 最 大 长 度 分 配 等 长 的 内 存 存放 ， 这 
样 太 浪费 ) 、 摘 述 红 黑 树 结 点 的 结构 体 、 最 近 访 问 时 间 。 如 果 为 每 条 记 
录 分 配 3 块 内 存 各 目 独 立 存 放 ， 似 乎 是 很 自然 的 、 符 合 软件 工程 的 行 
为 。 然 而 ， 应 当 考 虑 到 Slab 内 存 管理 机 制 因为 强调 速度 而 采用 了 best-fit 
思想 ， 这 么 做 会 产生 最 大 1 倍 内 存 的 浪费 ， 所 以 ， 在 设计 数据 存储 时 应 
当 尽 量 把 1 条 记录 的 3 条 数据 放 在 1 块 连续 内 存 上 。 如 何 实 现 呢 ? 























先 回 顾 下 7.5.3 节 中 给 出 的 ngx_rbtree_node t 的 定义 : 


typedef struct ngx_rbtree node s ngx_rbtree node t; 
struct ngx_rbtree node s { 
// 每 个 结 点 的 





hash 值 


ngx_rbtree_key_t key; 
// 左 子 结 点 ， 由 


Nginx 红 黑 树 自动 维护 
ngx_rbtree_node 上 *Jeft 
// 右 子 结 点 ， 由 
Nginx 红 黑 树 自动 维护 
ngx_rbtree_node 上 *right 


// 父 节点 ， 由 


Nginx 红 黑 树 自动 维护 


ngx_rbtree_node 上 *parent; 
// 红色 、 黑 色 ， 由 


Nginx 红 黑 树 自动 维护 
u_char color; 
// 无 用 
u_char data, 
}; 





红 黑 树 中 的 每 个 结 点 都 对 应 着 一 个 ngx_rbtree_node_t 结 构 体 ， 它 的 
key 成 员 必 须要 设置 ， 因 为 比较 哈 希 过 的 整 型 要 比 挨个 比较 字符 串 中 的 
字符 快 得 多 ! 它 的 data 成 员 目 前 是 无 用 的 ， 其 他 成 员 由 ngx_rbtree 上 自行 处 





接着 ngx_rbtree_node_t 的 color 成 员 之 后 (和 窗 新 data 成 员 ) ， 开 始 定 
义 我 们 的 结构 体 ngx_http_testslab_node_t， 如 下 所 示 : 





typedef struct { 
// 对 应 于 


ngx_rbtree_node 七 最 后 一 个 


data 成 . 员 


u_char rbtree_node_data,; 
// 按 先 后 顺序 把 所 有 访问 结 点 串 起 ， 方 便 淘汰 过 期 结 点 


ngx_queue_t queue; 
// 上 一 次 成 功 访问 该 


URL 的 时 间 ， 精 确 到 毫秒 


ngx_msec 七 Jast 
// 客户 端 


IP 地 址 与 


URL 组 合 而 成 的 字符 串 长 度 


u_short len; 
// 以 字符 串 保 存 客户 端 


IP 地 址 与 


URL 
u_char data[1]; 
} ngx_http_testslab node _t; 


二 一 


ngx_http_testslab_ node _t 上 接 ngx_rbtree_node _ t、 下 接 变 长 字符 串 ， 
一 条 访问 记录 就 是 这 样 存放 在 一 块 连续 内 存 上 的 ， 如 图 16-1 所 示 。 





nex_rbtree_node_t 的 data 成 员 地 址 可 ngx_http_testslab_node_1 


直接 转换 为 ngx_http_testslab_node_1 的 data 成 员 地 址 可 直接 转换 为 ipturl 


结构 体 的 字符 串 











dqueue 


ngx_rbtree_n 





ode_1 ngx_http_test 
slab_node_1 
图 16-1 用 一 段 连续 内 存 存放 红 黑 树 键 、 值 的 内 存 布 局 
由 于 多 个 进程 都 要 操作 红 黑 树 ， 摘 述 红 黑 树 的 ngx_rbtree_t 和 哨兵 结 








点 ngx_rbtree_node_t 都 必须 存放 在 共享 内 存 中 ， 同 理 ， 淘 汰 链表 的 表 头 
也 需要 存放 在 共享 内 存 中 ， 因 此 下 面 来 定义 结构 体 
ngx_http_testslab_shm_t， 它 会 存放 在 自 进 程 启动 起 从 slab 共 享 内 存 里 分 
配 的 第 1 块 内 存 中 : 











// ngx_http_testslab_shm_t 保 存在 共享 内 存 中 


typedef struct { 
// 红 黑 树 用 于 快速 检索 


ngx_rbtree_t rbtree; 
// 使 用 


Nginx 红 黑 树 必须 定义 的 哨兵 结 点 


ngx_rbtree_node 上 sentinel; 
// 所 有 操作 记录 构成 的 淘汰 链表 


ngx_queue_t queue; 
} ngx_http_testslab_shm_t; 








我 们 在 哪里 存放 来 自 共享 内 存 的 ngx_http_testslab_shm_t 结 构 体 的 指 
针 呢 ?在 这 个 例子 中 ， 由 于 仪 有 一 个 http{} 块 下 的 main 级 别 配 置 项 ， 这 
意味 着 对 这 个 模块 而 言 每 个 worker 进 程 仅 含 一 个 main 配 置 结构 体 ， 
此 ， 可 以 把 ngx_http_testslab_shm_t 的 指针 放 在 这 个 结构 体 里 。 





此 外 ， 描 述 slab 共 享 内 存 的 ngx_slab_pool t 结 构 体 指针 也 可 以 这 样 
放置 。 所 以 ， 我 们 定义 的 配置 结构 体 ngx_http_testslab_conf t 就 是 这 样 
的 : 





// 注意 : 


ngx_http_testslab_conf_t 不 是 放 在 共享 内 存 中 的 


typedef struct { 
// 共享 内 存 大 小 


ssize_t shmsize; 
// 两 次 成 功 访问 所 必须 间隔 的 时 间 


ngx_int_t interval; 
// 操作 共享 内 存 一 定 需要 


ngx_slab_pool tt 结构 体 


// 这 个 结构 体 也 在 共享 内 存 中 


ngx_S]lab_pool 七 *Shpool 
// 指向 共享 内 存 中 的 


ngx_http_testslab_shm_t 结 构 体 


ngx_http_testslab_shm_t* sh; 
} ngx_http_testslab_conf_t; 





shmsize 和 interval 成 员 仅 为 nginx.conf 里 的 配置 项 ， 其 中 interval 还 用 
于 表示 是 否 通 过 配置 项 开启 了 模块 的 功能 。 











16.2.2 ”操作 共享 内 存 中 的 红 黑 树 与 链表 








在 7.2 闻 中 介绍 过 双向 链表 ， 它 的 操作 很 简单 ， 在 这 个 例子 中 当 需 
要 删除 结 点 时 调用 ngx_queue_remove 方 法 ， 淘 汰 结 点 时 则 从 链表 尾部 开 
始 这 历 ， 使 用 ngx_queue_last 方 法 可 以 获取 到 尾部 的 结 点 ， 而 插入 新 结 
点 时 用 ngx_queue_insert_head 方 法 插入 链表 首部 即 可 。 





在 7.5 节 中 介绍 过 红 黑 树 ， 删 除 结 点 时 调用 ngx_rbtree_delete 方 法 即 
可 ， 由 于 参数 中 直接 传递 的 是 结 点 指针 ， 因 此 这 里 不 需要 做 任何 处 理 。 
但 是 插入 、 遍 历时 就 稍 复杂 些 ， 因 为 每 个 结 点 的 真实 关键 字 是 一 个 变 长 
字符 串 ，ngx_rbtree_node_t 中 的 key 成 员 放 的 是 字符 串 的 hash 值 ， 所 以 插 
入 函数 时 不 能 直接 使 用 预 置 的 ngx_rbtree_insert_value 方 法 。 我 们 需要 定 


义 一 个 新 的 insert 方 法 ， 并 在 初始 化 红 黑 树 时 把 该 方法 传递 给 
ngX_rbtree_init 的 第 3 个 参数 。 当 然 ， 定 义 一 个 新 的 insert 方 法 没有 想象 中 
那么 难 ， 只 需要 参考 ngx_rbtree_insert_value 方 法 的 实现 即 可 ， 该 方法 认 
为 ngx_rbtree_node _t 中 的 key 成 员 束 是 关键 字 ， 而 我 们 则 认为 字符 串 才 是 
真正 的 关键 字 ，key 仅 用 于 加 速 操 作 红 黑 树 ， 所 以 稍微 改 改 就 可 以 用 

于 


读者 朋友 在 继续 阅读 前 可 以 先 浏 览 下 src/core/ngx_rbtree.c 中 的 
ngx_rbtree_insert_value 方 法 源码 ， 这 里 不 再 列 出 。 





void 
ngx_rbtree_insert value(ngx_rbtree node t *temp, ngx_rbtree node t *node, ngx_rbtree 








接着 ， 开 始 实现 针对 图 16-1 中 这 种 内 存 布局 记录 的 红 黑 树 插 入 方法 


ngx_http_testslab_rbtree_insert_value: 





static void 
ngx_http_testslab_rbtree insert value(ngx_rbtree node t *temp, 
ngx_rbtree node t *node, ngx_rbtree node t *sentinel) 





ngx_rbtree_node 上 **p; 
ngx_http_testslab_node 上 *]rn, *lrnt; 
for (;; ){ 
// ngx_rbtree_node tt 中 的 
Key 仅 为 
hash 值 


// 先 比较 整 型 的 


key 可 以 加 快 插入 速度 


if (node->key < temp->key) { 
p = &temp->left; 

} else if (node->key > temp->key) { 
p = &temp->right,; 

} else { /* node->key == temp->key */ 
// 从 


data 成 员 开 始 就 是 


ngx_http_testslab_node_t 结 构 体 


lrn = (ngx_http_testslab node t *) &node->data; 
lrnt = (ngx_http_testslab node t *) &temp->data; 
p = (ngx_memn2cmp(lrn->data, lrnt->data, lrn->len, lrnt->len) < 0) &temr 


if (*p == sentinel) { 
break; 


temp = *p; 


*p = node; 

node->parent = temp; 
node->left = sentinel; 
node->right = sentinel,; 
ngx_rbt_red(node); 





在 实现 了 插入 方法 后 ， 就 可 以 像 下 面 这 样 初 始 化 红 黑 树 了 : 





ngx_http_testslab conf_t *conf; 


ngx_rbtree_init(&conf->sh->rbtree, &conf->sh->sentinel, 
ngx_http_testslab_rbtree_insert_value); 








下 面 ， 我 们 开始 实现 含有 业务 逻辑 的 ngx_http_testslab_lookup 和 
ngx_http_testslab_expire 方 法 ， 前 者 含有 红 黑 树 的 遍历 。 


ngX_http_testslab lookup 负 责 在 http 请 求 到 来 时 ， 首 先 利用 红 黑 树 的 
快速 检索 特性 ， 看 一 看 共享 内 存 中 是 否 存在 访问 记录 。 碍 找 记 录 时 ， 首 














先 碍 找 hash 值 ， 奉 相同 再 比较 字符 串 ， 在 该 过 程 中 都 按 左 子 树 小 于 右 子 
树 的 规则 进行 。 如 果 查 找到 访问 记录 ， 则 检查 上 次 访问 的 时 间距 当前 的 
时 间 差 是 否 超 过 允许 阀 值 ， 超 过 了 则 更 新 上 次 访问 的 时 间 ， 并 把 这 条 记 
录 重 新 放 到 双向 链表 的 首部 (因为 眼下 这 条 记录 最 不 容易 被 淘汰 ) ， 同 
时 返回 NGX_DECLINED 表 示人 允许 访问 ; 若 没 有 超过 阀 值 ， 则 返回 

NGX_HTTP_FORBIDDEN 表 示 拒 绝 访 问 。 如 果 红 黑 树 中 没有 查找 到 这 
条 记录 ， 则 向 slab 共 享 内 存 中 分 配 一 条 记录 所 需 大 小 的 内 存 块 ， 并 设置 
好 相应 的 值 ， 同 时 返回 NGX_DECLINED 表 示人 允许 访问 。 代 码 如 下 : 

















// Tr 是 


http 请 求 ， 因 为 只 有 请 求 执 行 时 才 会 调用 





ngx_http_testslab_lookup 
// conf 是 全 局 配置 结构 体 


// data 和 


en 参数 表示 


IP+URL 字 符 串 ， 而 


hash 则 是 该 字符 串 的 


hash 值 


static ngx_int_ 
ngx_http_testslab lookup(ngx_http_request_t *r, 
ngx_http_testslab_conf_t *conf, 
ngx_uint_t hash， 
u_char* data, 
size_t len) 


size_t size; 
ngx_int_t re; 


ngx_time_t “tp; 


ngx_msec_t Now; 
ngx_msec_int_t ms; 
ngx_rbtree_node_t *node, *sentinel; 


ngx_http_testslab node t *1r; 
// 取 到 当前 时 间 


tp = ngx_timeofday(); 

now = (ngx_msec_t) (tp->sec * 1000 + tp->msec); 
node = conf->sh->rbtree.root,; 

sentinel = conf->sh->rbtree.sentinel,; 

while (node != sentinel) { 


// 先 由 


hash 值 快速 查找 请 求 


If (hash < node->key) { 
node = node->]left 
continue; 


if (hash > node->key) { 
node = node->right,; 
continue; 
} 
/* hash == node->key */ 
lr = (ngx_http_testslab node t *) &node->data.; 
// 精确 比较 


IP+URL 字 符 串 


rc = ngx_memn2cmp(data, lr->data, len, (size t) lr->len); 
if (rc == 0) { 
// 找到 后 先 取 得 当前 时 间 与 上 次 访问 时 间 之 差 


ms = (ngx_msec_int_t) (now - lr->last); 
// 判断 是 否 超 过 阀 值 


if (ms > conf->interval) { 
// 允许 访问 ， 则 更 新 这 个 结 点 的 上 次 访问 时 间 


lr->last = now; 
// 不 需要 修改 该 结 点 在 红 黑 树 中 的 结构 


// 但 需要 将 这 个 结 点 移动 到 链表 首部 


ngx_dqueue_remove(&lLr->queue ) 
ngx_queue_insert_head(&conf->sh->queue, &lr->queue); 
// 返回 





NGX_DECLINED 表 示 当 前 
handler 允 许 访问 ， 继 续 向 下 执行 ， 参 见 


10.6.7 节 


return NGX_DECLINED; 


403 拒 绝 访问 ， 参 见 
19.6.7 节 


return NGX_HTTP_FORBIDDEN ， 


node = (rc < 0) node->left : node->right,; 


} 
// 获取 到 连续 内 存 块 的 长 度 


size = offsetof(ngx_rbtree node t, data) 
+ offsetof(ngx_http_testslab node t, data) 
+ len; 

// 首先 尝试 淘汰 过 期 


node ， 以 释放 出 更 多 共享 内 存 


ngx_http_testslab_ expire(r, conf); 
// 释放 完 过 期 访问 记录 后 就 有 更 大 机 会 分 配 到 共享 内 存 


// 由 于 已 经 加 过 锁 ， 所 以 没有 调用 


ngx_slab_alloc 方 法 


node = ngx_slab alloc locked(conf->shpool, size); 


if (node == NULL) { 
// 共享 内 存 不 足 时 简单 返 错 ， 这 个 简单 的 例子 没有 做 更 多 的 处 理 


return NGX_ERROR,; 
} 
// key 里 存放 
ip+ur1 字 符 事 的 


hash 值 以 加 快 访问 红 黑 树 的 速度 


node->key = hash 
Jr = (ngx_http_testslab node t *) &node->data; 
// 设置 访问 时 间 


lr->last = now; 
// 将 连续 内 存 块 中 的 字符 串 及 其 长 度 设置 好 


lr->len = (u_char) len; 
ngx_memcpy(lr->data, data, len); 
// 插入 红 黑 树 


ngx_rbtree_insert(&conf->sh->rbtree, node); 
// 插入 链表 首部 





ngx_queue_insert_head(&conf->sh->queue, &lr->queue); 
// 允许 访问 ， 参 见 


10.6.7 节 


return NGX_DECLINED ， 








ngx_http_testslab_expire 方 法 则 负责 从 双 同 链表 的 尾部 开始 检查 访问 
记录 ， 如 果 上 次 访问 的 时 间距 当前 已 经 超出 了 人 允许 阀 值 ， 则 可 以 删除 访 
问 记 录 从 而 释放 共享 内 存 。 代 码 如 下 : 





static void 
ngx_http_testslab_expire(ngx_http_request_t *r,ngx_http_testslab conf_t *conf) 


ngx_time_t *tp; 
ngx_msec_t now; 
ngx_queue_t *q; 
ngx_msec_int_t ms; 
ngx_rbtree_node 上 *node 


ngx_http_testslab node t *1r; 
// 取出 缓存 的 当前 时 间 


tp = ngx_timeofday(); 
now = (ngx_msec_t) (tp->sec * 1000 + tp->msec); 
// 循环 的 结束 条 件 为 ， 要 么 链表 空 了 ， 要 么 遇 到 了 一 个 不 需要 淘汰 的 结 点 


while (1) { 
// 要 先 判断 链表 是 否 为 空 


if (ngx_queue _ empty(&conf->sh->queue)) { 
// 链表 为 空 则 结束 循环 


return 


} 
// 从 链表 尾部 开始 淘汰 


// 因为 最 新 访问 的 记录 会 更 新 到 链表 首部 ， 所 以 尾部 是 最 老 的 记录 





q = ngx_queue_ last(&conf->sh->queue); 
// ngx_queue_data 可 以 取出 


ngx_queue_t 成 员 所 在 结构 体 的 首 地 址 


lr = ngx_queue data(q, ngx_http_testslab node _t, queue); 
// 可 以 从 


lr 地 址 向 前 找到 


ngx_rbtree_node_t 
node = (ngx_rbtree node t *) 
((u_char *) lr - offsetof(ngx_rbtree node t, data)); 
// 取 当 前 时 间 与 上 次 成 功 访问 的 时 间 之 差 


ms = (ngx_msec_int t) (now - lr->last); 
If (ms < conf->interval) { 
// 若 当 前 结 点 没有 淘汰 掉 ， 则 后 续 结 点 也 不 需要 淘汰 


return 


} 
// 将 淘汰 结 点 移出 双向 链表 


ngx_queue_remove(q); 
// 将 淘汰 结 点 移出 红 黑 树 


ngx_rbtree delete(&conf->sh->rbtree, node); 
// 此 时 再 释放 这 块 共享 内 存 


ngx_slab_free_ locked(conf->shpool, node); 





准备 工作 环绕 ， 接 下 来 可 以 开始 定义 http 过 小 模块 了 。 


16.2.3 ”解析 配置 文件 


首先 定义 ngx_command_t 结 构 体 处 理 nginx.conf 配 置 文件 ， 并 在 其 后 
接 2 个 参数 的 test_slab 配 置 项 ， 它 仅 能 存放 在 http{} 块 中 ， 代 人 码 如 下 : 





static ngx_command t ngx_http_testslab commands[] = { 
{ ngx_string("test_slab"), 
// 仅 支 持 在 


http 块 下 配置 


test_slab 配 置 项 


// 必须 携带 


2 个 参数 ， 前 者 为 两 次 成 功 访问 同一 


URL 时 的 最 小 间隔 秒 数 


// 后 者 为 共享 内 存 的 大 小 


NGX_HTTP_MAIN_CONF|NGX_CONF_TAKE2， 
ngx_http_testslab_createmem, 


F 
9, 
NULL }, 
ngx_null_ command 


}; 





下 面 实现 解析 配置 项 的 方法 ngx_http_testslab_createmem。 只 有 当 发 
现 test_slab 配 置 项 上 且 其 后 跟着 的 参数 都 合法 时 ， 才 会 开局 模块 的 限 速 功 
能 。 代 码 如 下 : 





static char * 
ngx_http_testslab_ createmem(ngx_conf_t *cf, ngx_command t *cmd, void *conf) 


ngx_str_t *Value ; 
ngx_shm_zone_t *shm_zone; 
// conf 参 数 为 


ngx_http_testslab_create_main_conf 创 建 的 结构 体 


ngx_http_testslab conf_t *mconf = (ngx_http_testslab conf_t *)conf; 
// 这 块 共享 内 存 的 名 字 


ngx_str_t name = ngx_string("test_slab_shm"); 
// 取 到 


test_slab 配 置 项 后 的 参数 数组 


value = cf->args->elts; 
// 获取 两 次 成 功 访问 的 时 间 间 隔 ， 注 意 时 间 单 位 


mconf->interval = 1000*ngx_atoi(value[1].data, value[1].1en); 
If (mconf->interval == NGX_ERROR || mconf->interval == 0) { 
// 约定 设置 为 


-1 就 关闭 模块 的 限 速 功能 


mconf->interval = -1; 
return "Invalid value",; 


} 
// 获取 共享 内 存 大 小 


mconf->shmsize = ngx_parse_size(&value[2]); 
If (mconf->shmsize == (ssize _t) NGX ERROR || mconf->shmsize == 0) { 
// 关闭 模块 的 限 速 功能 


mconf->interval = -1; 
return "Invalid value",; 
} 
// 要 求 


Nginx 准 备 分 配 共享 内 存 


shm_ zone = ngx_shared memory_add(cf, &name, mconf->shmsize, 
&ngx_http_testslab_ module); 





if (shm zone == NULL) { 
// 关闭 模块 的 限 速 功能 


mconf->interval = -1; 
return NGX_CONF_ERROR ; 


} 
// 设置 共享 内 存 分 配 成 功 后 的 回调 方法 


shm_zone->init = ngx_http_testslab_shm_init; 
// 设置 


jnit 回 调 时 可 以 由 
data 中 获取 


ngx_http_testslab_conf_t 配 置 结构 体 


shm_zone->data = mconf ， 
return NGX_CONF_OK 





全 局 ngx_http_testslab_conf t 配 置 结构 体 的 生成 由 


ngx_http_testslab_create_main_conf 方 法 负责 ， 它 会 设置 到 


ngx_http_module t 中 。 其 代码 如 下 : 





static void * 
ngx_http_testslab_create main conf(ngx_conf_t *cf) 


ngx_http_testslab conf_t *conf; 
// 在 


worker 内 存 中 分 配 配置 结构 体 


conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_testslab conf_t)); 
if (conf == NULL) { 
return NULL; 


// interval 初 始 化 为 


-1 ， 同 时 用 于 判断 是 否 未 开启 模块 的 限 速 功能 


conf->interval = -1; 
conf->shmsize = -1; 
return conf; 





ngx_shared_memory_add 执 行 成 功 后 ，Nginx 将 会 在 所 有 配置 文件 解 


析 完 毕 后 开始 分 配 共 享 内 存 ， 并 在 名 为 test_slab_shm 的 slab 共 享 内 存 初 
始 化 完毕 后 回调 ngx_http_testslab_shm init 方 法 ， 该 方法 实现 如 下 : 





static ngx_int_t 
ngx_http_testslab_shm init(ngx_shm zone _t *shm zone, void *data) 


{ 





ngx_http_testslab conf_t *conf; 


// data 可 能 为 空 ， 也 可 能 是 上 次 


ngx_http_testslab_shm_init 执 行 完成 后 的 


shm_zone->data 
ngx_http_testslab conf_t *oconf = data; 
size_t len; 
// shm_zone->data 存 放 着 本 次 初始 化 


CyCle 时 创建 的 


ngx_http_testslab_conf_t 配 置 结构 体 


= 
ie 
“x 


_http_testslab conf_t *)shm zone->data,; 


~ 
< 
芭 川 
同一 
i 
这 


re1Load 配 置 项 后 导致 的 初始 化 共享 内 存 


if (oconf) { 
// 本 次 初始 化 的 共享 内 存 不 是 新 创建 的 


// 此 时 ， 
data 成 员 里 就 是 上 次 创建 的 


ngx_http_testslab_conf_t 
// 将 


sh 和 


Shpool 指 针 指 向 旧 的 共享 内 存 即 可 


conf->sh = oconf->sh,; 
conf->shpool = oconf->shpool; 
return NGX_OK; 


} 
// shm.addr 里 放 着 共享 内 存 首 地 址 


:ngx_slab_pool 二 结构 体 


conf->shpool = (ngx_slab pool t *) shm zone->shm.addr; 


// Slab 共享 内 存 中 每 一 次 分 配 的 内 存 都 用 于 存放 


ngx_http_testslab_shm_t 
conf->sh = ngx_slab_alloc(conf->shpool, sizeof(ngx_http_testslab_shm_ t)); 
if (conf->sh == NULL) { 
return NGX_ERROR,; 


conf->shpool->data = conf->sh,; 
// 初始 化 红 黑 树 


ngx_rbtree_init(&conf->sh->rbtree, &conf->sh->sentinel, 
ngx_http_testslab_rbtree_insert_value); 
// 初始 化 按 访问 时 间 排 序 的 链表 





ngx_queue_init(&conf->sh->queue); 
// Slab 操作 共享 内 存 出 现 错误 时 ， 其 


10g 输 出 会 将 


log_ctx 字 符 串 作为 后 级 ， 以 方便 识别 


len = sizeof(" in testslab \"\"") + shm zone->shm.name.1en; 
conf->shpool->log_ctx = ngx_slab_alloc(conf->shpool, len); 
if (conf->shpool->log ctx == NULL) { 

return NGX_ERROR,; 
} 


ngx_sprintf(conf->shpool->log_ ctx, " in testslab \"%V\"%zZ", 
&shm_zone->shm.name); 
return NGX_OK， 





16.2.4 定义 模块 


先 定 义 http 模 块 的 回调 接口 ngx_http_testslab module_ctx， 设 置 main 
级 别 配置 结构 体 的 生成 方法 为 ngx_http_testslab_create_main_conf (因为 
是 main 级 别 ， 所 以 不 需要 实现 其 merge 合 并 配置 项 方法 ) ， 再 设置 http 配 
置 项 解析 完毕 后 的 回调 方法 ngx_http_testslab_init， 用 于 在 11 个 http 请 求 


处 理 阶 段 中 选择 一 个 处 理 请 求 ， 如 下 所 示 : 





static ngx_http_module t ngx_http_testslab module ctx = 





{ 
NULL, /* preconfiguration */ 
ngx_http_testslab_init, /* postconfiguration */ 
ngx_http_testslab_create main conf, /* create main configuration */ 
NULL， /* init main configuration */ 
NULL， /* create server configuration */ 
NULL， /* merge server configuration */ 
NULL, /* create location configuration */ 
NULL /* merge location configuration */ 
}; 





ngx_http_testslab_init 方 法 用 于 设置 本 模块 在 
NGX HTTP PREACCESS_ PHASE 阶段 生效 ， 代 码 如 下 : 





static ngx_int_ 
ngx_http_testslab_init(ngx_conf_t *cf) 


ngx_http_handler_pt *h; 

ngx_http_core _ main conf_t *cmcf,; 

cmcf = ngx_http_conf_get_ module main conf(cf, ngx_http_core module); 
// 设置 模块 在 








NGX_HTTP_PREACCESS_PHASE 阶 段 介 入 请 求 的 处 理 


h = ngx_array_push(&cmcf->phases[NGX_HTTP_PREACCESS_PHASE] .handlers); 
if (h == NULL) { 
return NGX_ERROR 


} 
// 设置 请 求 的 处 理 方法 


*h = ngx_http_testslab_handler; 
return NGX_OK， 





这 里 请 求 的 处 理 方法 被 设置 为 ngx_http_testslab_handler 了 ， 因 为 在 
15.2.2 节 中 己 经 准备 好 了 ngx_http_testslab_lookup 方 法 ， 所 以 它 的 实现 就 


变 得 很 简单 ， 如 下 所 示 : 





static ngx_int_t 
ngx_http_testslab_handler(ngx_http_request _t *r) 


{ 
size_t len; 
Uint32_t hash,; 
ngx_int_t rec; 


ngx_http_testslab_ conf_t *conf; 

conf = ngx_http_get _ module main conf(r, ngx_http_testslab module); 
rc = NGX_DECLINED ; 

// 如 果 没 有 配置 





test_slab, 或 者 


test_slab 参 数 错误 ， 返 回 


NGX_DECLINED 继 续 执行 下 一 个 


http handler 
if (conf->interval == -1) 
return rc; 
// 以 客户 端 


IP 地 址 〈 


r->connection->addr_text 中 已 经 保存 了 解析 出 的 


IP 字 符 串 ) 


// 和 


Url 来 识别 同一 请 求 


len = r->connection->addr_text.len + r->uri.len; 

u_char* data = ngx_palloc(r->pool, len); 

ngx_memcpy(data, r->uri.data, r->uri.1len); 

ngx_memcpy(data+r->uri.len, r->connection->addr_text.data, r->connection->addr_t 
// 使 用 


crc32 算 法 将 


IP+URL 字 符 串 生成 


hash 三 


// hash 码 作为 红 黑 树 的 关键 字 来 提高 效率 


hash = ngx_crc32_short(data, len); 
// 多 进程 同时 操作 同一 共享 内 存 ， 需 要 加 锁 


ngx_shmtx_lock(&conf->shpool->mutex); 


rc = ngx_http_testslab lookup(r, conf, hash, data, len); 


ngx_shmtx_unlock(&conf->shpool->mutex ); 
return rc; 





最 后 ， 定 义 ngx_http_testslab_module 模 块 : 





ngx_module t ngx_http_testslab module = 
{ 





NGX_MODULE_V1, 


&ngx_http_testslab module ctx, /* 
ngx_http_testslab_commands, /* 
NGX_HTTP_MODULE, /* 
NULL, /* 
NULL, /* 
NULL, /* 
NULL, /* 
NULL, A/* 
NULL, /* 
NULL, /* 


NGX_MODULE_V1_PADDING 
}; 





module context */ 
module directives */ 
module type */ 


init 
init 
init 
init 
exit 
exit 
exit 


master */ 
module */ 
process */ 
thread */ 
thread */ 
process */ 
master */ 


这 样 ， 一 个 支持 多 进程 间 共 享 数 据 、 共 同 限 制 用 户 请 求 访问 速度 的 


模块 束 完 成 了 。 


16.3 slab 内 存 管 理 的 实现 原理 





怎样 动态 地 管理 内 存 呢 ? 先 看 看 需要 面 对 的 两 个 主要 问题 : 


` 在 时 间 上 ， 使 用 者 会 随机 地 申请 分 配 、 释 放 内 存 ; 


. 在 空间 上 ， 每 次 申请 分 配 的 内 存 大 小 也 是 随机 的 。 


这 两 个 问题 将 给 内 存 分 配 算法 带 来 很 大 的 挑战 : 当 多 次 分 配 、 释 放 
不 同 大 小 的 内 存 后， 将 不 可 避免 地 造成 内 存 碎片 ， 而 内 存 碎 片 会 造成 内 
存 浪 费 、 执 行 速度 变 慢 ! 常见 的 算法 有 2 个 设计 方向 : first-fit 和 best-fit。 
用 最 简单 的 实现 方式 来 描述 这 2 个 算法 就 是 ， 若 已 使 用 的 内 存 之 间 有 许 
多 不 等 长 的 空 亲 内存， 那么 分 配 内 存 时 ，first-fit 将 从 头 遍 历 空闲 内 存 块 
构成 的 链表 ， 当 找到 的 第 1 块 空 间 大 于 请 求 size 的 内 存 块 时 ， 就 把 它 返 回 
给 申请 者 ;best-fit 则 不 然 ， 它 也 会 遍历 空 亲 链表， 但 如 果 一 块 空闲 内 存 
的 空间 远大 于 请 求 size， 为 了 避免 浪费 ， 它 会 继续 向 后 遍历 ， 看 看 有 没 
有 恰好 适合 申请 大 小 的 空 闪 内 存 块 ， 这 个 算法 将 试图 返回 最 适合 (例如 
内 存 块 大 小 等 于 或 者 略 大 于 申请 size) 的 内 存 块 。 这 样 ，first-fit 和 best- 
fit 的 优 劣 仿佛 已 一 目 了 然 : 前 者 分 配 的 速度 更 快 ， 但 内 存 浪费 得 多 ;后 
者 的 分 配 速度 慢 一 些 ， 内 存 利用 率 上 却 更 划算 。 而 且 ， 前 者 造成 内 存 碎 
片 的 几率 似乎 要 大 于 后 者 。 














Nginx 的 slab 内 存 分 配方 式 是 基于 best-fit 思 路 的 ， 即 当 我 们 申请 一 块 
内 存 时 ， 它 只 会 返回 恰好 符合 请 求 大 小 的 内 存 块 。 但 是 ， 怎 样 可 以 更 快 
速 地 找到 best-fit 内 存 块 呢 ? Nginx 首 先 有 一 个 假定 : 所 有 需要 使 用 slab 内 
存 的 模块 请 求 分 配 的 内 存 都 是 比较 小 的 〈 绝 大 部 分 小 于 4KB) 。 有 了 这 
个 假定 ， 就 有 了 一 种 快速 找到 最 合适 内 存 块 的 方法 ， 主 要 包括 5 个 要 
点 ; 





1) 把 整 块 内 存 按 4KB 分 为 许多 页 ， 这 样 ， 如 果 每 一 页 只 存放 一 种 
固定 大 小 的 内 存 块 ， 由 于 一 页 上 能 够 分 配 的 内 存 块 数量 是 很 有 限 的 ， 所 
以 可 以 在 页 首 上 用 bitmap 方 式 ， 按 二 进 制 位 表示 页 上 对 应 位 置 的 内 存 块 
是 侍 在 使 用 中 。 只 是 志 历 bitmap 二 进 制 位 去 寻找 页 上 的 空 用 内 存 块 ， 使 
得 消耗 的 时 间 很 有 限 ， 例 如 bitmap 占 用 的 内 存 空间 小 导致 CPU 缓存 命中 
率 启 ， 可 以 按 32 或 64 位 这 样 的 总 线 长 肛 去 寻找 空 用 位 以 减少 访问 次 数 


有 
等 。 


所 有 空闲 页 构成 链表 









ngx_slab_page_t 


ngx_slab_page_t 


同等 块 构成 的 半 满 \ 


页 构成 链表 ， 并 置 
于 相应 slot 下 


ngx_slab_page_t 






脱离 半 满 页 
链表 


允许 1 个 超大 
块 使 用 1 个 或 
者 多 个 页 面 


ngx_slab_page_t 


ngx_slab_page_t 


图 16-2 slab 内存 示意 图 


2) 基于 空间 换 时 间 的 思想 ，slab 内 存 分 配器 会 把 请 求 分 配 的 内 存 大 
小 简化 为 极为 有 限 的 几 种 《简化 的 方法 有 很 多 ， 例 如 可 以 按照 fibonacci 
方法 进行 ) ， 而 Nginx slab 是 按 2 的 倍数 ， 将 内 存 块 分 为 8、16、32、 
64..…. 字 节 ， 当 申请 的 字 贡 数 大 于 8 小 于 等 于 16 时 ， 就 会 使 用 16 字 节 的 
内 存世 ， 以 此 类 推 。 所 以 ， 一 种 页 面 知 存放 的 内 存 块 大 小 为 N 字 节 ， 那 
么 ， 使 用 者 申请 的 内 存在 NM2+1 与 N 之 间 时 ， 都 将 使 用 这 种 页 面 。 这 样 
最 多 会 造成 一 倍 内 存 的 浪费 ， 但 使 得 页 种 类 大 大 减少 了 ， 这 会 降低 碎片 
的 产生 ， 提 高 内 存 的 利用 率 。 


























3) 让 有 限 的 几 种 页 面 构成 链表 ， 且 各 链表 按 序 保存 在 数组 中 ， 这 
样 一 来 ， 用 直接 寻 址 法 就 可 以 快速 找到 。 在 Nginx slab 中 ， 用 slots 数 组 来 
存放 链表 首页 。 例 如 ， 如 果 申 请 的 内 存 大 小 为 30 字 节 ， 那 么 根据 最 小 的 
内 存 块 为 8 字 节 ， 可 以 算出 从 小 到 大 第 3 种 内 存 块 存放 的 内 存 大 小 为 32 字 
节 ， 符 合 要求 ， 从 slots 数 组 中 取 第 3 个 元 素 则 可 以 寻找 到 32 字 节 的 页 
面 。 




















4) 这 些 页 面 中 分 为 空 亲 页 、 半 满 页 、 全 满 页 。 为 什么 要 这 么 划分 
呢 ? 因为 上 述 的 同 种 页 面 链表 不 应 当 包含 太 多 元 隶 ， 人 否则 分 配 内 存 时 通 
历 链表 一 样 非常 耗 时 。 所 以 ， 全 满 页 应 当 脱 离 链 表 ， 分 配 内 存 时 不 应 当 
再 访问 到 它 。 空 用 页 应 该 是 超然 的 ， 如 果 这 个 页 面 曾经 为 32 字 市 的 内 存 














块 服务 ， 在 它 又 成 为 空 用 页 时 ， 下 次 便 可 以 为 128 字 节 的 内 存 块 服务 。 
因此 ， 所 有 的 空间 页 会 单独 构成 一 个 空 用 页 链表 。 这 里 slots 数 组 采用 散 
列表 的 思想 ， 用 快速 的 直接 寻 址 方式 将 半 满 页 展现 在 使 用 者 面前 。 








5) 虽然 大 部 分 情况 下 申请 分 配 的 内 存 块 是 小 于 4KB 的 ， 但 极 个 别 
可 能 会 有 一 些 大 于 4KB 的 内 存 分 配 请 求 ， 拒 绝 它 则 太 粗 暴 了 。 对 于 此 ， 
可 以 用 遍历 空闲 页 链表 寻找 地 址 连续 的 空闲 页 来 分 配 ， 例 如 需要 分 配 
11KB 的 内 存 时 ， 则 过 历 到 3 个 地 址 连续 的 空闲 页 即 可 。 





以 上 5 点 ， 就 是 Nginx slab 内 存 管理 方法 的 主要 思想 ， 如 图 16-2 所 


图 16-2 中 ， 每 一 页 都 会 有 一 个 ngx_slab_page_t 结 构 体 描述 ，object 是 
申请 分 配 到 的 内 存 存 放 的 对 象 ， 阴 影 方块 是 已 经 分 配 出 的 内 存 块 ， 空 日 
方块 则 是 未 分 配 的 内 存 块 。 下 面 开始 详细 描述 slab 算 法 。 





16.3.1 内 存 结构 布局 





每 一 个 slab 内 存 池 对 应 着 一 块 共享 内 存 ， 这 是 一 段 线性 的 连续 的 地 
址 空间 ， 这 里 不 只 是 有 将 要 分 配给 使 用 者 的 应 用 内 存 ， 还 包括 slab 管 理 
结构 ， 事 实 上 从 这 块 内 存 的 首 地 址 开始 就 是 管理 结构 体 
ngx_slab_pool_t， 我 们 看 看 它 的 定义 : 





typedef struct { 


// 为 下 面 的 互 斥 锁 成 员 


ngx_shmtx_t muteXx 服 务 ， 使 用 信号 量 作 进 程 同步 工具 时 会 用 到 它 


ngx_shmtx_sh_t lock; 
// 设 定 的 最 小 内 存 块 长 度 


size_t min_size; 
// min_size 对 应 的 位 偏 移 ， 因 为 


Slab 的 算法 大 量 采用 位 操作 ， 从 下 面 章节 里 可 以 看 出 先 计 算出 


// min_shift 很 有 好 处 


size_t min_shift; 
/7 :每 一 页 对 应 一 林 


ngx_slab_page_t 页 描述 结构 体 ， 所 有 的 


ngx_slab_page_ 七 存放 在 连续 的 


// 内 存 中 构成 数组 ， 而 


pages 就 是 数组 首 地 址 


ngx_slab _ page t *pages; 
// 所 有 的 空闲 页 组 成 一 个 链表 挂 在 


free 成 员 上 


ngx_slab_page_t free; 
// 所 有 的 实际 页 面 全 部 连续 地 放 在 一 起 ， 第 


1 页 的 首 地 址 就 是 


start 
u_char *start; 
// 指向 这 段 共享 内 存 的 尾部 


u_char *end; 


14.8 节 中 曾 介 绍 过 


Nginx 封 装 的 互 斥 锁 ， 这 里 就 是 一 个 应 用 范例 


ngx_shmtx_t mutex; 
// Slab 操 作 失 败 时 会 记录 日 志 ， 为 区 别 是 哪个 


Slab 共 享 内 存 出 错 ， 可 以 在 


Slab 中 分 配 一 段 内 存 存 


// 放 描 述 的 字符 串 ， 然 后 再 用 


10g_ctx 指 向 这 个 字符 串 


u_char *log_ctx; 
// 实际 就 是 


'\0'， 它 为 上 面 的 


log_ctx 服 务 ， 当 


10g_Cctx 没 有 赋值 时 ， 将 直接 指向 


Zero， 


// 表示 空 字符 串 防止 出 错 


u_char zero; 
// 由 各 个 使 用 


Slab 的 模块 自由 使 用 ， 


Slab 管 理 内 存 时 不 会 用 到 它 


void *data; 
// 指向 所 属 的 


ngx_shm_zone_ 七 里 的 


ngx_shm_t 成 员 的 


addr 成 员 ， 在 


16.3.3 节 再 详 述 


void *addr; 
} ngx_slab_pool_t; 





从 图 16-3 中 可 以 看 到 ， 这 段 共 享 内 存 由 前 至 后 分 为 6 个 部 分 : 
ngx_slab_pool_t 结 构 体 。 


` 不 同 种 类 页 面 的 半 满 页 链表 构成 的 数组 ， 下 文 称 为 slots 数 组 ， 便 
于 大 家 对 照 Nginx 源 码 。 将 共享 内 存 首 地 址 加 上 sizeof(ngx_slab_pool b 即 


可 得 到 slots 数 组 。 


" 所 有 页 描述 ngx_slab_page_t 构 成 的 数组 ，ngx_slab_pool_t 中 的 pages 


成 员 指 向 这 个 数组 ， 下 文 简称 为 pages 数 组 。 


` 为 了 让 地 址 对 齐 、 方 便 对 地 址 进行 位 操作 而 “牺牲 的 ”不 予 使 用 
的 内 存 。 


` 真实 的 页 ， 页 中 的 地 址 需要 对 齐 以 便 进 行 位 操作 ， 因 此 其 前 后 会 


有 内 存 浪 费 。ngx_slab_pool t 中 的 start 成 员 指 向 它 。 
` 为 了 地 址 对 齐 牺牲 的 内 存 。 


图 16-3 中 一 个 slab 共 享 内 存 与 ngx_shm_zone_t 和 ngx_cycle_t 的 关系 将 
在 16.3.5 节 中 详 述 。 下 面 来 看 看 slots 数 组 与 pages 数 组 是 如 何 工作 的 。 
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图 16-3 ”一 个 slab 共 享 内 存 池 中 的 内 存 布局 


无 论 是 slots 数 组 还 ee 都 是 以 页 为 单位 进行 的 ， 页 在 slab 
管理 设计 中 是 很 核心 的 概念 。 每 一 页 都 有 一 个 描述 结构 ngx_slab_page_t 
对 应 ， 下 面 来 看 看 ngx_slab_page_t 的 定义 是 怎样 的 。 








typedef struct ngx_slab page s ngx_slab_ page t; 
struct ngx_slab page s { 
// 多 用 途 





uintptr_t Slab 
// 指向 双向 链表 中 的 下 一 页 


ngx_slab_page t *next; 
// 多 用 途 ， 同 时 用 于 指向 双向 链表 中 的 上 一 页 


uintptr_t prev; 


站 





从 图 16-2 中 可 以 看 到 ， 页 分 为 空闲 页 和 已 使 用 页 ， 而 已 使 用 页 中 又 
分 为 还 有 空闲 空间 可 供 分 配 的 半 满 页 和 完全 分 配 完毕 的 全 满 页 。 每 一 页 
的 大 小 由 ngx_pagesize 变 量 指定 ， 同 时 为 方便 大 量 的 位 操作 ， 还 定义 了 
页 大 小 对 应 的 位 移 变 量 ngx_pagesize_shift， 如 下 : 











ngx_uint_t ngx_pagesize,; 
ngx_uint_t ngx_pagesize_shift; 








这 两 个 变量 可 在 ngx_os_init 方 法 中 初始 化 ， 如 下 : 





ngx_int_t ngx_os_init(ngx_log _t *1og) 





ngx_pagesize = getpagesize() 
for (n = ngx_pagesize; n >>= 1; ngx_pagesize shift++) { /* void */ } 





全 满 页 和 空闲 页 较为 简单 。 全 满 页 不 在 任何 链表 中 ， 它 对 应 的 
ngx_slab_page_t 中 的 next 和 prev 成 员 没 有 任何 链表 功能 。 


所 有 的 空 闪 页 构成 1 个 双向 链表 ，ngx_slab_pool_t 中 的 free 指 向 这 个 
链表 。 然 而 需要 注意 的 是 ， 并 不 是 每 一 个 空闲 页 都 是 该 双向 链表 中 的 元 
素 ， 可 能 存在 多 个 相 邻 的 页 面 中 ， 仅 首页 面 在 链表 中 的 情况 ， 故 而 首页 
面 的 slab 成 员 大 于 1 时 则 表示 其 后 有 相 邻 的 页 面 ， 这 些 相 邻 的 多 个 页 面 作 
为 一 个 链表 元 素 存 在 。 但 是 ， 也 并 不 是 相 邻 的 页 面 一 定 作 为 一 个 链表 元 
素 存 在 ， 如 图 16-4 所 示 。 























在 图 16-4 中 ， 有 5 个 连续 的 页 面 ， 左 边 是 描述 页 面 的 ngx_slab_page 
结构 体 ， 右 边 则 是 真正 的 页 面 ， 它 们 是 一 一 对 应 的 。 其 中 ， 第 1、2、 
4、5 页 面 都 是 空 首页， 第 3 页 则 是 全 满 页 。 而 free 链 表 的 第 1 个 元 素 是 第 5 
页 ， 第 2 个 元 素 是 第 4 页 ， 可 见 ， 虽 然 第 4、5 页 是 连续 的 ， 但 是 ， 由 于 分 
配 页 面 与 回收 页 面 时 的 时 序 不 同 ， 导 致 这 第 4、5 个 页 面 间 出 现 了 相 见 不 
相识 的 现象 ， 只 能 作为 2 个 链表 元 系 存 在 ， 这 将 会 造成 末 来 分 配 不 出 占 
用 2 个 页 面 的 大 块 内 存 ， 昌 然 原本 是 可 以 分 配 出 的 。 第 3 个 元 素 是 第 1 
页 。 第 2 页 附 在 第 1 页 上 ， 这 还 是 与 分 配 、 回 收 页 面 的 时 机 有 关 ， 事 实 
上 ， 当 slab 内 存 池 刚 刚 初 始 化 完毕 时 ，free 链 表 中 只 有 1 个 元 隶 ， 惑 是 第 1 









































个 页 面 ， 该 页 面 的 slab 成 员 值 为 总 页 数 。 第 3 页 是 全 满 页 ， 其 next 指 针 是 


为 NULL， 而 prev 也 没有 指针 的 含义 。 





ngx_slab_pool 上 


并 名 
< 







next 的 free 成 员 
prev 
a 该 页 面 是 相 邻 
页 ， 它 的 成 员 
没有 意义 ， 由 
: 前 面 页 面 的 slab 
prev 
全 满 页 脱离 于 
任何 链表 ， 其 
next 和 prev 成 
| 员 没 有 链接 的 
| 然 相 邻 ,但 它 
们 之 间 并 不 知 
| 道 ， 所 以 ,各 
i 自 独立 的 存在 


于 链表 中 





图 16-4 ”空闲 页 与 全 满 页 的 ngx_slab_page_t 成 员 意 义 








对 于 半 满 页 ， 存 放 相 同 大 小 内 存 块 的 页 面 会 构成 双 癌 链表 ， 挂 在 
slots 数 组 的 相应 位 置 上 ， 图 16-2 中 已 经 可 以 看 到 。 那 么 ， 页 面 上 究竟 会 
分 出 多 少 种 不 同 大 小 的 内 存 块 呢 ? 





ngx_slab_pool t 中 的 min_size 成 员 已 经 指定 了 最 小 内 存 块 的 大 小 ， 
它 在 初始 化 Slab 的 方法 ngx_slab_init 中 赋值 : 





void ngx_SsJab_init(ngx_slab_pool t *pool) 


pool->min_size = 1 << pool->min_shift,; 





而 min_shift 同 样 是 为 了 位 操作 而 设 的 ， 它 的 初始 化 则 是 将 在 16.3.3 
节 介 绍 的 ngx_init_zone_pool 方 法 里 赋值 的 : 





static ngx_int_t 
ngx_init_zone_pool(ngx_cycjle_t *cycle, ngx_shm_ zone_t *zn) 


ngx_slab pool t *sp; 


sp->min_shift = 3; 








页 面 能 够 存放 的 最 大 内 存 块 大 小 则 由 变量 ngx_slab_max_size 指 定 : 





// 存放 多 个 内 存 块 的 页 面 中 ， 人 允许 的 最 大 内 存 块 大 小 为 


ngx_slab_max_size 
static ngx_uint t ngx_slab_ max_size; 








它 的 大 小 实际 是 页 面 大 小 的 一 半 《 在 ngx_slab_init 方 法 中 设置 ) : 





if (ngx_Sslab_max_Ssize == 0) { 
ngx_slab_max_size = ngx_pagesize / 2; 








为 什么 是 ngx_pagesize/2 而 不 干脆 就 是 ngx_pagesize 呢 ?反正 一 个 页 
面 只 存放 一 个 内 存 块 也 可 以 啊 ! 这 是 因为 slab 中 把 不 等 长 的 内 存 大 小 分 





为 了 4 个 大 类 ， 这 样 分 类 后 ， 可 以 使 得 ngx_slab_page_t 的 3 个 成 员 与 实际 
页 面 的 内 存 管 理 在 时 间 和 空间 上 更 有 效率 。 这 4 大 类 的 定义 还 需要 1 个 变 


量 ngx_slab_exact_size 的 参与 ， 如 下 : 





static ngx_uint_t ngx_slab_exact_size; 
static ngx_uint t ngx_slab_exact_shift; 











它 的 赋值 也 在 ngx_slab_init 方 法 中 进行 : 





ngx_slab_exact_size = ngx_pagesize / (8 * sizeof(uintptr_t)); 

for (n = ngx_slab_ exact_ size; n >>= 1; ngx_slab exact_ shift++) { 
/* void */ 

} 





ngx_slab_exact_size 到 底 想 表达 什么 意思 呢 ? 


其 实 就 是 ，ngx_slab page t 的 Slab 中 是 否 可 以 恰好 以 bitmap 的 方式 指 
明 页 面 中 所 有 内 存 块 的 使 用 状态 。 例 如 ，1 个 三 进 制 位 束 可 以 用 0 和 1 表 
示 内 存 块 是 否 被 使 用 ，slab 成 员 的 类 型 是 uintptr_t， 它 有 sizeof(uintptr_t) 











个 字 节 ， 每 个 字 节 有 8 位 ， 这 样 按 顺 序 slab 就 可 以 表示 8*sizeof(uintptr_t) 
个 内 存 块 。 如 果 1 个 页 面 中 正好 可 以 存放 这 么 多 内 存 块 ， 那 么 slab 就 可 以 
只 当做 bitmap 使 用 ， 此 时 ， 该 页 面 存放 的 内 存 块 大 小 就 是 
ngx_pagesize/(8*sizeof(uintptr_t))。 以 此 作为 标准 划分 ， 就 可 以 更 精确 地 
使 用 slab 成 员 了 。 表 16-1 就 展示 了 4 类 内 存 是 怎样 划分 的 ， 以 及 
ngx_slab_page_t 各 成 员 的 意义 。 


表 16-1 


小 块 内 存 ， 小 于 ngx_ 


slab_ exact size 


中 等 内 存 ， 等 于 ngx_ 


slab exact size 


大 块 内 存 ， 大 于 ngx_ 
slab_exact size 而 小 于 


ngx slab max size 


超大 内 存 ， 大 于 等 于 


ngx slab max size 





4 类 内 存 中 页 面 描述 ngx_slab_page_t 的 各 成 员 意 义 


ngx_slab_page + 


表示 该 页 面 上 存放 的 等 长 内 存 块 | 指向 双向 链表 的 下 | 低 2 位 为 11， 以 NGX_ 
大 小 ， 当 然 是 用 位 依 移 的 方式 存放 | 一 个 元 素 ， 如 果 不 在 |SLAB SMALL 表示 当前 页 
的 双向 链表 中 ， 则 为 0 | 面 存放 的 是 小 块 内 存 

低 2 位 为 10， 以 NGX_ 
SLAB _ EXACT 表示 当前 页 
面 存放 的 是 中 等 大 小 的 内 存 






作为 bitmap 表示 页 上 的 内 存 块 是 
否 已 被 使 用 


高 TDC_STORAGE _ MAP _ 
MASK 位 表示 bitmap， 而 低 TDC_ 
STORAGE_SHIFT MASK 位 表示 存 


低 2 位 为 01， 以 NGX 
SLAB_BIG 表示 当前 页 面 存 
放 的 是 大 块 内 存 


放 的 内 存 块 大 小 


超大 内 存 会 使 用 1 页 或 者 多 页 ， 
这 些 页 都 在 一 起 使 用 。 对 于 这 批 页 
面 中 的 第 1 页，slab 的 前 3 位 会 被 低 2 位 为 00， 以 NGX_ 
设 为 NGX SLAB PAGE START， 洒 世 SLAB PAGE 表示 当前 页 面 
其 余 位 表示 紧 随 其 后 相 邻 的 同 批 页 是 以 整 页 来 使 用 
面 数 ; 反之，slab 会 被 设 为 NGX 
SLAB PAGE BUSY 


16.3.2 ”分配 内 存 流程 


分 配 内 存 时 ， 主 要 涉及 在 半 满 面 上 分 配 和 从 空间 页 上 分 配 新 页 ， 并 





初始 化 这 2 个 流程 ， 而 半 满 页 分 配 又 涉及 在 bitmap 上 查找 空闲 块 ， 对 于 
小 块 、 中 等 、 大 块 内 存 这 三 种 页 面 而 言 ， 其 bitmap 放 置 的 位 置 并 不 相 
同 ， 图 16-5 主 要 说 明了 以 上 内 容 ， 下 面 详细 解释 图 中 的 15 个 步 又 。 


1) 如 采用 户 申请 的 内 存 size 大 于 前 文 介绍 过 的 ngx_slab_max_size 变 
量 ， 则 认为 需要 按 页 面 来 分 配 内 存 ， 此 时 跳 转 到 步骤 2;， 人 否则， 由 于 一 
个 页 面 可 以 存放 多 个 内 存 块 ， 因 此 需要 考虑 bitmap， 此 时 跳 转 到 步 又 6 
继续 执行 。 





2) 判断 需要 分 配 多 少 个 页 面 才能 存放 size 字 节 ， 不 足 1 页 时 按 1 页 
算 。 如 下 : 





ngx_uint_t pages = (size >> ngx_pagesize shift) + ((size % ngx_pagesize) ?1 : 0) 








[ 若 size 小 于 ngx_slab_max_size] 人 于 等 于 ngx_slab_max_size] 


6 ) 算出 恰好 可 放置 size 的 内 存 块 大 小 





2 ) 根据 请 求 大 小 计算 出 需要 多 少 个 连续 页 面 





7 ) 取得 内 存 块 所 属 半 满 页 链表 slots 





3 ) 从 free 池 中 寻找 连续 的 N 个 页 面 


8 ) 遍历 半 满 页 链表 [判断 是 否 找到 ] 


[没有 半 满 页 ] 


12 ) 从 free 池 中 分 配 1 个 页 面 i 


< [没有 空闲 页 ] 


[分 配 到 1 个 空闲 页 ] | 
@ ) 回 NULL 表 示 失 败 


3 ) 设置 页 面 为 存储 某 长 度 的 页 面 


<> 


[找到 一 个 半 满 页 ] 
[当前 页 面 是 全 满 页 ， 脱 离 链表 ] 













[找到 空闲 chunkl] 





10 ) 置 空闲 内 存 块 对 应 bitmap 位 为 1 








14 ) 设置 bitmap 第 1 位 或 者 前 n 位 为 已 使 用 
[根据 bitmap 判 此 [页 面 是 否 已 满 ] | 





5 ) 蔡 该 页 面 插入 半 满 页 链表 的 首部 
[页 面 还 有 空闲 内 悔 块 ] 


<> 


[没有 空闲 内 存 块 ] 


11 ) 将 该 页 面 分 离 出 半 满 链表 





5 ) 返回 内 存 块 首 地 址 


图 16-5 “分 配 slab 内 存 的 流程 


3) 遍历 free 空 闲 页 链表 ， 找 到 能 够 容纳 下 size 的 连续 页 面 。 如 果 只 
需要 分 配 1 页 ， 那 么 很 简单 ， 只 要 退 历 到 空 闪 页 就 可 以 结束 ; 但 如 果 要 
分 配 多 页 ，free 链 表 中 的 每 个 页 描述 ngx_slab_page_t 中 的 slab 指 明了 其 后 
连续 的 空闲 页 数 ， 所 以 获取 多 个 连续 页 面 时 ， 只 要 查找 free 链 表 中 每 个 
元 素 的 slab 是 否 大 于 等 于 pages 页 面 数 即 可 。 下 面 针 对 分 配 页 面 的 
ngx_slab_alloc_pages 方 法 进行 说 明 : 











static ngx_slab_ page 七 * 
ngx_slab_alloc pages(ngx_silab_pool t *pool, ngx_uint_t pages) 


ngx_slab_page t *page, *p; 
// 遍历 


free 空 闲 页 链表 ， 参 见 图 


16-4 
for (page = pool->free.next; page != &pool->free; page = page->next) { 
// 表明 连续 页 面 数 足以 容纳 
Size 字 节 


if (page->slab >= pages) { 
// 如 果 链 表 中 的 这 个 页 描述 指明 的 连续 页 面 数 大 于 要 求 的 


pages， 只 取 所 需 即 可 ， 


// 将 剩余 的 连续 页 面 数 仍然 作为 一 个 链表 元 素 放 在 


free 池 中 


if (page->slab > pages) { 
// page[pages] 是 这 组 连续 页 面 中 ， 


1 个 不 被 使 用 到 的 页 ， 所 以 ， 


// 将 由 它 的 页 描述 
ngx_Sslab_page tt 中 的 


SJab 来 表明 后 续 的 连续 页 数 


page[pages].slab = page->slab - pages; 
// 接 下 来 将 剩余 的 连续 空闲 页 的 第 


1 个 页 描述 


page[pages] 作 为 


// 链表 元 素 插入 到 
free 链 表 中 ， 取 代 原 先 所 属 的 


page 页 描述 


// 将 


page[pages] 的 链表 指向 当前 链表 元 素 的 前 后 元 素 


page[pages],next = page->next; 
page[pages].prev = page->prev; 
// 将 链表 的 上 一 个 元 素 指向 


page[pages] 
p = (ngx_slab_ page t *) page->prev; 
p->next = &page[pages]; 
// 将 链表 的 下 一 个 元 素 指向 

page[pages] 


page->next->prev = (uintptr_t) &page[pages]; 
} else { 
// Slab 等 于 


pages 时 ， 直 接 将 


page 页 描述 移出 


free 链 表 即 可 


p = (ngx_Sslab_page _t *) page->prev; 
p->next = page->next,; 
page->next->prev = page->prev; 


} 

// 这 段 连续 页 面 的 首页 描述 的 
Slab 里 ， 高 
3 位 设 


NGX_SLAB_PAGE_START 
page->slab = pages | NGX_SLAB_PAGE_START ， 
// 不 在 链表 中 


page->next = NULL; 
// prev 定 义 页 类 型 : 存放 


Size>=ngx_slab_max_size 的 页 级 别 内 存 块 


page->prev = NGX_SLAB_PAGE; 
If (--pages == 0) { 
// 如 果 只 分 配 了 


1 页 ， 此 时 就 可 以 返回 


page 了 
return page; 
} 
// 如 果 分 配 了 连续 多 个 页 面 ， 后 续 的 页 描述 也 需要 初始 化 
for (p = page + 1; pages; pages--) { 
// 连续 页 作为 一 个 内 在 块 一 起 分 配 出 时 ， 非 第 
1 页 的 
Slab 都 置 为 


NGX_SLAB_PAGE_BUSY 
p->slab = NGX_SLAB_ PAGE_BUSY; 


p->next = NULL; 
p->prev = NGX_SLAB_PAGE; 
p++; 


} 
// 连续 的 各 个 页 描述 都 初始 化 完成 后 ， 返 回 页 


page 

} 

} 

// 没有 找到 符合 要 求 的 页 面 ， 返 回 


return page 


NULL 
return NULL 
} 





介绍 完 ngx_slab_alloc_pages 方 法 可 知 ， 如 果 找 到 符合 要 求 的 页 面 ， 
那么 跳 到 第 5 步 ， 返 回 页 面 的 首 地 址 即 可 ; 没有 找到 这 样 的 页 面 ， 跳 到 
第 4 步 返 回 NULL。 





) 返回 NULL， 表 明 分 配 不 出 新 内 存 ，OutOfMemory。 


) 返回 可 以 使 用 的 内 存 块 首 地 址 。 





6) slab 页 面 上 允许 存放 的 内 存 块 以 8 字 节 起 步 ， 知 字 节 数 在 
ngx_slab max_size 以 内 时 是 按 2 的 倍数 递增 的 ， 那 么 这 与 第 2 步 按 页 分 配 
时 是 不 同 的 ， 按 页 分 配 时 最 多 浪费 ngx_pagesize-1 字 节 的 内 存 ， 例 如 分 
配 4097 字 市 时 必须 返回 2 个 连续 页 ， 而 按 2 的 倍数 分 配 时 ， 则 最 多 会 浪费 
size-2 字 节 内 存 ， 例 如 分 配 9 字 节 时 应 返回 16 字 节 的 内 存 块 ， 浪 费 了 7 个 


i 


此 时 size 小 于 ngx_slab_max_size， 因 此 要 依据 best-fit 原 则 找 一 个 恰 


好 能 放下 size 的 内 存 块 大 小 。 


7) 取出 所 有 半 满 页 链表 构成 的 slots 数 组 ， 由 于 链表 是 以 内 存 块 从 
小 到 大 以 2 的 整数 倍 按 序 放 在 数组 中 的 ， 所 以 使 用 直接 寻 址 的 方式 找到 
第 6 步 指示 的 内 存 块 所 属 半 满 页 链表 。 


8) 过 历 半 满 页 链表 。 如 果 没 有 找到 半 满 页 ， 则 跳 到 第 12 步 去 分 配 
新 页 存放 该 内 存 块 ， 找 到 一 个 半 满 页 ， 则 继续 执行 第 9 步 。 


9) 根据 表 16-1 可 知 ， 当 内 存 块 小 于 ngx_slab_max_size 时 ， 每 页 都 
必须 使 用 bitmap 来 标识 内 存 块 的 使 用 状况 。 而 依据 bitmap 的 存放 位 置 不 
同 ， 又 分 为 小 块 、 中 等 、 大 块 内 存 。 此 时 ， 需 要 根据 第 6 步 算出 的 内 存 
块 大 小 ， 先 找到 bitmap 的 位 置 ， 再 遍历 它 找到 第 1 个 空闲 的 内 存 块 。 如 
果 找 到 空闲 内 存 块 ， 则 继续 执行 第 10 步 ， 和 否则 ， 这 个 半 满 面 就 名 不 符 实 
了 ， 它 实际 上 就 是 一 个 全 满 页 ， 所 以 可 以 脱离 半 满 页 链表 了 ， 继 续 第 8 
步 遍 历 链 表 。 





10) 首先 将 找到 的 空 用 内 存 块 对 应 的 bitmap 位 置 为 1， 以 示 内 存 块 
在 使 用 中 。 接 着 ， 检 查 这 是 否 为 当前 页 的 最 后 一 个 空 几 内 存 块 ， 如 果 
是 ， 则 半 满 页 变 为 全 满 页 ， 跳 到 第 11 步 执行 ， 否 则 ， 直 接 跳 到 第 5 步 ， 
返回 这 个 内 存 块 地 址 。 





11) 将 页 面 分 离 出 半 满 页 链表 ， 再 跳 转 到 第 5 步 。 


12) 未 找到 半 满 页 ， 需 要 从 free 空 亲 页 链表 中 申请 出 新 的 一 页 ， 参 
见 第 3 步 介 绍 过 的 ngx_slab_alloc_pages 方 法 ， 如 果 未 分 配 出 新 页 ， 跳 到 








13) 设置 新 页 面 存放 的 内 存 块 长 度 为 第 6 步 指定 的 值 。 同 时 设置 它 
的 页 摘 述 的 prev 成 员 低位 ， 指 明 它 是 小 块 、 中 等 还 是 大 块 内 存 块 页 面 。 





14) 新 页 面 分 配 出 了 第 1 个 内 存 块 ， 对 于 中 等 、 大 块 内 存 页 来 说 ， 
置 bitmap 第 1 位 为 1 即 可 ， 但 对 于 小 块 内 存 页 ， 由 于 它 的 前 几 个 内 存 块 是 
用 于 bitmap 的 ， 因 此 不 能 再 次 被 使 用 ， 所 以 对 应 的 bit 位 需要 置 为 1， 并 
把 下 一 个 表明 当前 分 配 出 的 内 存 块 的 bit 位 也 置 为 1。 


15) 这 个 新 页 面 由 空闲 页 变 为 半 满 页 ， 因 此 将 页 面 插 入 半 满 页 链表 
的 首部 。 
16.3.3 ”释放 内 存 流程 

释放 内 存 时 不 需要 遍历 链表 、bitmap， 所 以 速度 更 快 。 图 16-6 说 明 
了 释放 内 存 的 完整 流程 。 

释放 内 存 的 流程 如 图 16-6 所 示 。 


1) 首先 判断 释放 的 内 存 块 地 址 是 否 合法 ， 依 据 为 是 否 在 
ngx_slab_pool_t 的 start、end 成 员 指 示 的 页 面 区 之 间 。 如 果 不 合法 ， 直 接 





结束 释放 流程 ， 例 如 : 





void ngx_slab_ free_ locked(ngx_slab pool t *pool, void *p) 


{ 
if ((u_char *) p < pool->start || (u_char *) p > pool->end) { 
// p 地 址 非法 








2) 从 竺 释放 的 内 存 块 地 址 p 可 以 快速 得 到 它 所 属 的 页 描述 结构 体 ， 
如 下 : 





ngx_uint_t n= ((u_char *) p - pool->start) >> ngx_pagesize_shift,; 
ngx_slab_page _t * page = &pool->pages[n]; 





page 变 量 就 是 页 描述 结构 体 ， 在 16.3.4 节 会 详细 介绍 类 似 地 址 位 运 
算 。 


3) 根据 页 描述 结构 体 的 prev 成 员 ， 得 到 该 页 面 是 用 于 小 块 、 中 
等 、 大 块 的 内 存 ， 或 者 按 页 分 配 的 内 存 。 因 为 存放 小 块 、 中 等 、 大 块 内 
存 的 页 面 含 有 bitmap， 这 样 的 页 面 处 理 时 要 再 次 核实 bitmap 中 p 对 应 的 bit 
位 是 否 为 1， 防 止 重复 释放 ， 此 时 跳 到 第 5 步 执 行 ， 如 果 p 当 初 是 按 页 分 
配 的 ， 不 需要 考虑 bitmap， 释 放 起 来 更 简单 ， 继 续 执 行 第 4 步 











4) 由 页 描述 的 slab 成 员 可 以 获得 当前 使 用 的 内 存 究竟 占用 了 多 少 页 
(参考 图 16-5 的 第 3 步 ) ， 如 下 : 





ngx_uint_t pages = Slab & ~NGX_SLAB_ PAGE_START 


接着 ， 跳 到 第 11 步 调用 ngx_slab_free_pages 释 放 这 pages 个 页 面 。 


5) 这 个 页 面 存 放 了 多 个 内 存 块 ， 参 考 表 16-1 可 知 ， 从 页 描述 的 slab 
成 员 可 以 获取 这 个 页 面 存放 多 大 的 内 存 块 。 








6) 用 页 大 小 除 以 内 存 块 大 小 ， 可 以 得 到 需要 多 少 个 bit 位 来 存放 
bitmap。 再 根据 地 址 p 与 页 面 首 地 址 的 相对 偏 移 量 ， 计 算出 p 对 应 的 内 存 
块 占 用 了 bitmap 中 的 哪个 bit 位 。 








1 ) 判断 待 释放 的 地 址 是 否 在 共享 内 存 地 址 范围 内 


[ 待 释放 地 址 合法 ] 
2 ) 根据 参数 地 址 与 共享 内 存 起 始 地 址 之 差 ， 获 得 对 应 的 页 描述 


3 ) 由 prev 成 员 的 低 2 位 中 取出 该 页 面 的 类 型 
ey [释放 不 足 半 页 的 大 、 中 、 小 块 内 存 ] 


[释放 跨 1 到 多 页 的 超大 块 内 存 ] 





4 ) 根据 slab 计 算出 待 释放 的 页 面 数 





[ 竺 释放 地 址 不 合法 ] 
5 ) 根据 页 面 类 型 由 slab 取 出 该 页 存储 内 存 块 的 大 小 


6 ) 由 参数 地 址 与 所 在 页 地 址 差 的 偏 移 计算 出 bitmap 位 


7 ) 检查 内 存 块 对 应 bitmap 位 上 是 否 为 已 使 用 





[bitmap 显 示 内 存 块 使 用 中 ， 合 法 ] 
[bitmap 显 示 内 存 块 为 空闲 ， 重 复 释 放 不 处 理 ] 
8 ) 置 该 bitmap 位 为 0， 再 检查 当前 页 是 否 是 全 满 页 
[当前 页 是 半 满 页 ] 





9 ) 将 当前 页 加 入 半 满 页 链表 的 首位 ， 并 使 slot 指 向 它 


10 ) 检查 当前 页 bitmap 是 否 已 经 没有 已 分 配 chunk 


eS [页 上 还 有 在 使 用 的 chunk] 


[页 上 已 经 没有 任何 chunk] 





11 ) 释放 页 面 到 free 空 闲 页 链表 池 中 SS 





图 16-6 释放 slab 内 存 的 流程 


7) 检查 bitmap 中 该 内 存 块 对 应 的 bit 位 是 否 为 1。 如 果 是 1， 那 么 执 
行 第 8 步 继 续 释 放 ;， 否 则 ， 可 以 认为 当前 是 在 释放 一 个 已 经 被 释放 的 内 
存 ， 结 束 释 放流 程 。 


8) 将 这 个 bit 位 由 1 改 为 0， 这 样 如 果 原 先 这 是 一 个 全 满 页 ， 就 会 变 
为 半 满 页 ， 执 行 第 9 步 ; 否则 ， 和 直接 执行 第 10 步 。 


9) 当前 页 面 既 然 由 全 满 页 变 为 半 满 页 ， 就 必须 插入 slots 中 的 半 满 
页 链表 ， 供 下 次 分 配 内 存 时 使 用 。 





10) 检查 bitmap 中 是 否 还 有 值 为 0 的 bit 位 ， 判 断 当 前 页 是 否 变 为 空 
朵 页 ， 如 果 变 成 了 空 亲 页 ， 则 执行 第 11 步 将 它 加 入 到 free 链 表 中 。 





11) 回收 页 面 ，ngx_slab_free_pages 方 法 负责 将 这 些 页 面 插入 到 free 
链表 中 ， 我 们 看 看 它 的 实现 是 怎样 的 : 








static void 

ngx_slab_free_ pages(ngx_slab pool t *pool, ngx_slab_page_t *page, 
ngx_uint_t pages) 
ngx_slab_page t *prev; 
// page 将 会 加 入 到 

free 链 表 中 ， 连 续 页 面 数 为 

pages， 所 以 把 


Slab 置 为 


pages 
page->slab = pages--; 
// 除了 


page 本 身 ， 检 查 其 后 是 否 还 有 页 面 


if (pages) { 
// 将 紧邻 的 页 面 描述 结构 体 所 有 成 员 置 为 


ngx_memzero(&page[1]，pages * sizeof(ngx_slab_page_t)); 
// 将 释放 的 首页 
page 的 页 描述 插入 到 


free 链 表 的 首部 


page->prev = (uintptr_t) &pool->free'， 
page->next = pool->free.next,; 
page->next->prev = (uintptr_t) page; 
pool->free.next = page; 





16.3.4 如 何 使 用 位 操作 


本 节 以 较为 复杂 的 小 其 内 存 页 为 例 ， 介 绍 如 何 使 用 位 操作 来 加 速 分 
配 、 释 放 内 存 ， 方 便 读 者 朋友 阅读 星 梁 的 位 操作 部 分 源 代码 。 





除了 NGX_SLAB_PAGE 类 型 的 页 面 ， 每 个 页 面 都 可 以 存放 多 个 内 
存 块 。 这 样 ， 每 个 页 面 都 需要 有 一 个 bitmap 来 表示 每 一 个 内 存 块 究竟 是 
被 使 用 的 还 是 空闲 的 。 然 而 ， 如 果 一 个 页 面 存 放 的 内 存 块 大 小 小 于 
ngx_slab_exact_size， 那 么 一 个 uintptr_t 是 存放 不 下 bitmap 的 。 这 时 ， 将 
会 使 用 页 面 里 的 前 几 个 内 存 块 充当 bitmap， 如 图 16-7 所 示 。 





实际 上 图 16-7 描 述 了 一 种 在 小 块 内 存 半 洱 页 上 分 配 内 存 的 场景 。 下 


面 简 要 地 用 源码 中 用 到 的 各 种 位 操作 来 描述 这 一 过 程 。 








ngx_slab_pool t 


slots 数 组 


pages 成 员 





prev 低 2 位 表示 该 
页 存储 小 块 chunk 


相距 n 个 页 面 


start 成 员 


bitmap 中 每 个 二 进 制 位 表示 对 
应 的 内 存 块 是 否 被 使 用 ， 此 时 
从 1100... 置 为 1110.. 


图 16-7 小 块 内 存 页 面 的 bitmap 会 直接 占用 页 面 中 的 内 存 


用 户 在 ngx_slab_alloc 方 法 中 申请 size_t size 大 小 的 内 存 ， 而 slab 中 是 
按 2 的 窜 来 决定 页 面 能 够 存放 的 内 存 块 大 小 的 。 哪 一 种 大 小 的 内 存 块 恰 





好 能 够 容纳 size 字 节 呢 ? 很 简单 ， 如 下 所 示 : 





ngx_uint_t shift=1; 
size_t s; 
for (s = size - 1; s >>= 1; shift++) { /* void */ } 





这 样 ， 我 们 获得 了 位 操作 必需 的 、 恰 好 容纳 size 字 节 的 内 存 块 的 偏 
移 量 shift。 除 此 以 外 ， 还 需要 拿 到 slots 数 组 ， 这 里 放置 了 半 满 页 构成 的 
链表 ， 从 共享 首 地 址 数 起 ， 加 上 sizeof(ngx_slab_pool_b 字 节 即 可 拿 到 ， 
如 下 所 示 : 





ngx_slab_pool t *pool; 


ngx_slab_page _t *slots = (ngx_slab_page t *) ((u_char *) pool + sizeof(ngx_slab_porc 





slots 数 组 中 按照 内 存 块 大 小 的 顺序 〈 从 小 到 大 ) ， 依 次 存放 了 各 种 
等 长 块 页 面 构成 的 半 满 页 链表 。 选 用 哪 一 个 slots 数 组 呢 ? 用 shift 偏 移 减 
去 表达 最 小 块 的 min_shift 成 员 即 可 : 





ngx_uint_t Slot = shift - pool->min_shift,; 
ngx_slab_page _t *page = slots[slot].next,; 





这 样 ，page 就 将 是 一 个 半 满 页 。 如 果 slots 中 没有 半 满 页 ， 那 么 page 
是 NULL。 图 16-5 中 描述 的 场景 是 含有 半 满 页 的 ， 所 以 下 面 继续 基于 这 
个 假定 进行 说 明 。 





接着 ， 我 们 发 现 用 户 希 望 分 配 的 内 存 块 大 小 是 小 于 


ngx_slab_exact_size 的 ， 此 时 ， 首 先 要 找到 bitmap 的 初始 位 置 ， 准 备 按 位 
来 查找 到 空闲 块 。bitmap 其 实 就 在 页 面 的 首 地 址 上 ， 怎 样 用 位 操作 快速 
找到 页 面 呢 ? 从 图 16-5 中 可 以 看 到 ngx_slab_pool_t 的 pages 指 针 和 start 指 
针 ， 它 们 是 关键 ! 


上 面 找到 的 page 是 半 满 页 的 ngx_slab_page_t 描 述 结构 体 的 站 地 址 ， 
用 它 减 去 pages 就 可 以 得 到 该 页 面 在 整个 slab 中 是 第 N 个 页 面 ( 这 2 个 相 减 
的 变量 都 是 ngx_slab_page_t* 类 型 ) 。start 是 对 齐 后 slab 第 1 个 页 面 的 起 始 
地 址 ， 所 以 ，start 加 上 N*pagesize 就 可 以 得 到 该 半 满 页 的 实际 页 面 首 地 
址 ， 如 下 所 示 : 








uintptr_t p = (page - pool->pages) << ngx_pagesize_shift,; 
uintptr_t* bitmap = (uintptr_t *) (pool->start + p); 





这 样 ，bitmap 变 量 将 指向 bitmap 的 首 地 址 ， 同 时 也 指向 第 1 个 页 面 。 
对 于 小 块 内 存 来 说 ，1 个 uintptr_t 类 型 是 注定 存放 不 下 bitmap 的 。 到 了 按 
位 比较 找到 空闲 块 的 时 候 了 ， 然 而 为 了 加 快运 算 速 度 ， 我 们 并 不 能 总 按 
照 二 进 制 位 来 循环 进行 ， 可 以 先 用 uintptr_t 类 型 快速 与 
Oxffffffffffffffff 《下文 的 NGX_SLAB_BUSY 宏 〉 比较 ， 如 果 相 等 则 说 明 
没有 空闲 块 ， 而 不 等 时 才 有 必要 按 二 进 制 位 慢 慢 地 找 出 那个 空闲 块 。 所 
以 ， 现 在 我 们 有 必要 知道 ， 多 少 个 uintptr_t 类 型 可 以 完整 地 表达 该 页 面 
的 bitmap? 用 页 面 大 小 除 以 块 大 小 可 以 知道 页 面 能 存放 多 少 个 块 ， 除 以 
8 就 可 以 知道 需要 多 少 字 节 来 存放 bitmap， 再 除 以 sizeof(uintptr_t) 就 可 以 




















知道 需要 多 少 个 uintptr_t 来 存放 bitmap。 实 际 上 ， 这 一 系列 操作 下 面 这 
吾 句 就 可 以 做 到 : 





ngx_uint t map = (1 << (ngx_pagesize_shift - shift)) 
/ (Sizeof(uintptr t) * 8); 





这 里 避免 了 更 慢 的 除法 ， 这 束 是 位 操作 的 优势 ! map 就 是 bitmap 需 
要 的 总 uintptr_t 数 。 下 面 我 们 看 看 怎样 在 一 个 存放 小 块 内 存 的 半 满 面 
中 ， 根 据 bitmap 的 位 操作 快速 找到 空闲 块 。 








// 共 需 要 


map 个 


Uintptr_t 才 能 表达 完整 的 


bitmap 
for (uintptr tn= 0; n < map; N++) { 
// 通过 用 


uintptr_t 与 


NGX_SLAB_BUSY 比 较 ， 快速 


pass 掉 全 满 的 


uintptr_t 
if (bitmap[n] != NGX_SLAB_ BUSY) { 
// 确认 当前 


bitmap[n] 上 有 空闲 块 ， 再 一 位 一 位 的 查找 


for (uintptr_t m= 1, i = 0; m; m <<= 1, i++) { 
// 这 个 位 如 果 是 


1 则 表示 内 存 块 已 被 使 用 ， 继 续 循环 遍历 


if ((bitmap[n] & m)) { 
continue,; 


} 
// 既然 找到 了 空闲 位 ， 先 把 这 个 位 从 


bitmap[n] |= m; 
// 那么 ， 当 前 的 这 个 


bit 到 底 对 应 着 该 页 面 的 第 几 个 内 存 块 呢 ? 从 
n 和 


并 即 可 得 到 ， 


// n*sizeof(uintptr_t)*8+i。 再 使 用 


<<shiftRp 可 得 到 该 内 存 块 在 页 面 上 的 字 节 偏 移 量 


i= ((n * sizeof(uintptr_t) * 8) << shift) 
+ (i << shift); 
// p 就 是 那个 空闲 块 的 首 地 址 ， 用 


bitmap 加 上 字 节 偏 移 


得 到 


p = (uintptr_t) bitmap + i; 
// 后 续 还 有 操作 ， 例 如 判断 如 果 页 面 由 半 满 变 为 全 满 ， 则 脱离 链表 





如 果 没 有 半 满 页 ， 则 需要 从 free 空 闲 链表 中 分 配 出 1 页 ， 再 初始 化 该 


页 中 的 bitmap。 我 们 来 看 看 源码 中 是 怎样 用 位 操作 为 初始 化 bitmap 的 。 





// page 是 从 


free 空 闲 链表 中 新 分 配 出 的 页 面 ， 用 其 与 


pages 数 组 相 减 后 即 可 得 到 是 第 几 个 


洁 


面 > 


// 再 左 移 
ngx_pagesize_shift 即 表示 从 


start 起 到 实际 页 面 的 字 节 偏 移 量 


p = (page - pool->pages) << ngx_pagesize_ shift,; 
// bitmap 既 是 页 面 的 首 地 址 ， 也 是 


bitmap 的 起 始 


bitmap = (uintptr_t *) (pool->start + p); 
// Ss 为 该 页 存放 的 块 大 小 


s= 1 << shift,; 
// Nn 表示 需要 多 少 个 内 存 块 才能 放 得 下 整个 


bitmap 
n= (1 << (ngx_pagesize shift - shift)) A/ 8 / s; 
if (n == 0) { 
n = 1; 
} 
// 因为 前 
n 个 内 存 块 已 经 用 于 
bitmap 了， 它们 不 可 以 再 被 使 用 ， 所 以 置 这 些 内 存 块 对 应 的 


bit 位 为 


1。 因 为 





// bitmap 这 里 占用 的 内 存 块 数 ， 不 可 能 连 


] 


uintptr_t 都 放 不 下 ， 所 以 只 需要 设置 第 


1 个 


uintptr_t 即 可 


bitmap[0] = (2 << n) - 1; 
// map 表示 需要 多 少 个 


uintptr_t 才 能 放 得 下 整个 


bitmap 
map = (1 << (ngx_pagesize shift - shift)) / (sizeof(uintptr_t) 8); 
for (i = 1; i < map; i++) { 

// 设置 剩余 的 


bit 位 为 


bitmap[i] = 9; 


// 根据 前 述 


S 和 


n 的 意义 ， 可 知 


S*n 就 是 在 这 个 页 面 里 ， 第 


1 个 可 以 使 用 的 空闲 块 的 偏 移 字 节 数 。 


// 再 加 上 该 页 面 与 


Start 间 的 偏 移 量 ， 


p 就 是 空闲 块 与 


Start 间 的 偏 移 量 


p = ((page - pool->pages) << ngx_pagesize shift) + s * n; 
// 于 是 得 到 该 空闲 块 的 首 地 址 


p += (uintptr_t) pool->start,; 





而 释放 内 存 块 时 ， 位 操作 依然 可 以 大 大 加 速 执 行 时 间 。 





void ngx_slab_free_ locked(ngx_slab pool t *pool, void *p) 


// 内 存 块 指针 


p 与 


Start 之 间 的 偏 移 字 节 数 ， 除 以 页 面 字 节 数 的 结果 取 整 ， 就 是 


p 所 在 的 页 面 在 所 有 


// 页 面 中 的 序号 


ngx_uint t n= ((u_char *) p - pool->start) >> ngx_pagesize_ shift; 
// 根据 


n 就 取 到 了 


Pp 所 在 页 面 的 


ngx_slab_page_t 页 面 描述 结构 体 


ngx_slab_page_t * page = &pool->pages[n]; 
// 找到 页 面 对 应 的 


slab 
uintptr_t Slab = page->slab,; 
// Slab 的 低 


NGX_SLAB_PAGE_MASK 位 存放 的 是 页 面 类 型 


ngx_uint t type = page->prev & NGX_SLAB_ PAGE MASK; 





拿 到 了 type 后 ， 需 要 对 4 种 页 面 区 别 对 等 。 仍 然 以 小 块 内 存 举例 : 





// 对 于 小 块 内 存 ， 


Slab 的 低 


NGX_SLAB_SHIFT_MASK 位 存放 了 内 存 块 大 小 ， 


Shift 变 量 取出 了 块 大 小 的 位 移 量 


Shift = Slab & NGX_SLAB_SHIFT_MASK ， 
// Size 取 得 的 块 大 小 


size = 1 << shift， 
// 把 内 存 块 的 首 地 址 


p 按 页 大 小 取 余 数 ， 就 是 


p 相 对 于 该 页 面 首 地 址 的 偏 移 字 节 ， 再 除 以 块 大 小 ， 


// 那么 


n 就 是 该 内 存 块 在 页 面 中 的 序号 


n = ((uintptr_t) p & (ngx_pagesize - 1)) >> shift; 
// 现在 把 


n 这 个 序号 应 用 于 


bitmap。 


bitmap 可 能 由 多 个 


Uintptr tt 组 成 ， 而 


n 从 属于 某 一 个 


uintptr_t, 


uintptr_t 中 的 余数 表明 这 个 内 存 块 对 应 的 


bit 位 ， 在 其 所 属 的 


Uintptr_t 里 的 序号 ， 


// 并 把 


1 左 移 这 些 位 ， 这 样 ， 


p 内 存 块 


bit 位 所 在 


Uintptr 七 中 的 位 


m= (uintptr t) 1 << (n & (sizeof(uintptr t) * 8 - 1)); 
// n 再 除 以 


uintptr_t 能 够 表达 的 


bit 位 ， 此 时 表示 


p 内 存 块 对 应 的 那个 


bit 位 前 还 有 


n 个 表示 


bitmap 
// 的 


uintptr_t 
n /= (sizeof(uintptr_t) * 8); 
// 把 


p 的 相当 于 一 页 的 低位 去 掉 ， 此 时 


bitmap 就 是 该 页 面 的 首 地 址 ， 也 是 所 有 


bitmap 的 起 始 地 址 


bitmap = (uintptr_t *) ((uintptr_t) p & ~(ngx_pagesize - 1)); 
// 用 


bitmap[nj 与 


m 相 与 ， 可 以 再 次 确认 


p 相 对 应 的 内 存 块 是 否 是 在 使 用 中 ， 如 果 没 有 在 使 用 中 ， 


// 就 是 两 次 释放 了 


if (bitmap[n] & m) { 
// 释放 该 内 存 块 ， 其 实 就 是 把 


bit 位 从 


1 置 为 


0 
bitmap[n] &= ~m; 
// 下 面 还 要 检查 当前 页 面 是 否 完全 没有 已 使 用 内 存 块 了 ， 如 果 是 这 样 ， 需 要 回收 该 页 





对 于 中 等 内 存 块 、 大 块 内 存 块 页 面 来 说 ， 由 于 bitmap 是 放 在 slab 成 
员 中 的 ， 所 以 位 操作 会 更 简单 ， 这 里 就 略 过 。 


16.3.5 slab 内存 池 间 的 管理 


Nginx 允 许多 个 模块 各 自 独立 地 定义 slab 内 存 池 ， 这 意味 着 可 以 并 存 
多 个 slab 内 存 池 。 同 时 ，Nginx 人 允许 模块 A 定义 的 内 存 池 被 模块 B 使 用 ， 
这 样 内 存 池 间 必须 被 管理 起 来 。 描 述 整 个 Nginx 的 ngx_cycle_s 结 构 体 中 
有 一 个 链表 ， 保 存 着 所 有 的 slab 内 存 池 ， 如 下 所 示 : 





struct ngx_cycle s { 
ngx_list _t shared memory; 


} 





shared_memory 以 链表 的 方式 保存 着 ngx_shm_zone_t 结 构 体 。 前 面 
在 16.1 市 中 就 介绍 过 这 个 结构 体 ， 它 对 应 着 1 个 slab 共 享 内 存 池 。 
ngx_shm_zone_t 具 有 自己 的 名 字 ， 还 可 以 定义 自己 仅 能 够 被 某 个 模块 使 
用 (tag 成 员 ) 。ngx_shared_memory_add 方 法 就 是 在 向 shared_memory 链 
表 中 添加 描述 一 个 Slab 内存 池 的 ngx_shm_zone_t 结 构 体 ， 在 
ngx_init _ cycle 方法 中 ，Nginx 会 遍历 shared_memory 链 表 ， 依 次 地 初始 化 
每 一 个 slab 内 存 池 。 











16.4 ”小 结 


本 章 首 先 介绍 使 用 slab 内 存 池 的 方法 ， 并 以 一 个 有 代表 性 的 例子 介 
绍 使 用 它 的 方法 ， 读 者 朋友 可 以 结合 访问 本 书 网 站 上 可 以 运行 的 示例 代 
码 来 阅读 。 





接着 ， 我 们 开始 剖析 它 的 实现 ，slab 也 是 Linux 内 核 中 一 种 优秀 的 内 
存 管理 机 制 ， 理 解 其 设计 思想 不 只 有 助 于 开拓 思路 ， 更 可 以 改进 它 。 例 
如 ，slab 内 存 池 其 实 对 于 大 于 4KB 的 内 存 的 使 用 很 不 友好 ， 在 持续 的 分 
配 释放 中 ， 连 续 着 的 空闲 页 会 越 来 越 少 ， 尤 其 是 有 些 空闲 页 明明 是 连续 
的 ， 但 是 可 能 也 认为 它们 是 分 离 的 ， 就 像 图 16-4 中 的 例子 那样 。 又 比 
如 ， 假 定 我 们 申请 的 内 存 基本 都 是 在 4KB 以 上 的 ， 这 就 不 能 再 使 用 操作 
系统 的 页 大 小 作为 内 存 池 的 页 大 小 了 ， 可 以 通过 增加 页 的 大 小 以 提高 
存 的 使 用 率 〈 注 意 : 这 可 能 导致 ngx_slab_page ft 页 描述 的 slab 成 员 中 存 
放 的 内 存 块 大 小 位 移 超出 NGX_SLAB_SHIFT_ MASK， 需 要 综合 
i 














另外 ，slab 的 源码 体现 了 极为 优秀 的 编码 艺术 ， 大 量 的 位 操作 极 大 
地 提高 了 效率 ， 非 常 值得 C 程 序 员 们 认真 学 习 。 





